laravel-heyman turns route authorization into a readable chain

The problem: authorization logic scattered across controllers

laravel-heyman is a PHP package for Laravel whose repository description is a declarative style of authorization and validation. The scenarios it is built for are the ones where access rules grow across a codebase.

The README frames the problem with a story. A developer is asked to make a login form behave a certain way: if you visit the login form you should be a guest, otherwise you are redirected to a panel. The story adds a constraint that is the real point: you are not allowed to touch the existing code because it is sensitive, and you may break it.

The package's answer is to put the rule in a service provider boot method rather than in a controller or middleware, so the logic lives in one place and can be changed without editing the code that runs it.

The topics attached to the repository name the territory it covers, including access-control-list, laravel-acl, laravel-roles, laravel-roles-permissions, laravel-gate, laravel-validation and eloquent-validation. The README also states the package is integrated with the laravel-debugbar package out of the box, which suggests the rules are meant to be inspected while you develop rather than inferred from log files afterwards.

Situations, conditions, otherwise and the reaction

The API is a chain, and the README gives its shape.

HeyMan::  (situation) ->   (condition)   -> otherwise() -> (react

The line is cut off in the README, but the vocabulary is clear enough to describe the model. You name a situation, such as the route being visited, then you attach one or more conditions that must hold, then you define the reaction. The otherwise() step is the branch for when the conditions do not hold, which is how a redirect away from a panel gets expressed without an if statement at the call site.

Two other situations and conditions are named in the README. For views there is an alias example mapping whenYouMakeView to view. For conditions there is an alias example mapping youShouldBeGuest to beGuest. Those two names are the clearest statement of the intended usage: the package deals with the situation of visiting a route and with conditions about who the visitor is.

The design is explicitly the tell don't ask principle, which the README explains as telling the framework what to do in a situation rather than fetching information and then deciding. Alec Sharp's formulation is quoted in the README, in the form that procedural code gets information then makes decisions while object-oriented code tells objects to do things.

Rules live in the AuthServiceProvider boot method

The README answers the question of where to put the calls in two sentences: you may put them in AuthServiceProvider.php, or in any other service provider, in the boot method.

That location is the whole architecture. Because the rules are declared centrally rather than inline, the README's first structural benefit follows: authorization and guarding code is decoupled from the rest of the application, so controllers and routes carry less code and there is a single place where access is limited and requests are validated.

The facade is what you call.

use Imanghafoori\HeyMan\Facades\HeyMan;
// or
use HeyMan;  // <--- alias

The alias form is worth noting because it is what lets the aliasing feature exist at all. The README says you can alias methods such as whenYouMakeView to view and youShouldBeGuest to beGuest if the default syntax is too verbose, and that you should do it in the boot method. The same boot method therefore carries both the rules and the naming choices, which keeps the convention decision next to the rules it affects.

For a working example the README points at the council repository and specifically at its app/Providers/AuthServiceProvider.php file, describing it as a fork of a laracasts.com tutorial refactored to use the package. That file is the reference implementation to read before writing your own.

forget() lets an application override rules set inside a vendor package

The third structural benefit is the one that separates this package from a permission list you define once. The README argues the approach is particularly useful when you write a package that needs ACL but want your package users to be able to override the rules applied to your package routes.

A package sets its rules like this, in code that lives in the vendor folder and therefore cannot be edited.

// This is written in package and lives in vendor folder, So we can not touch it.
HeyMan::whenYouHitRouteName('myPackageRoute')->youShouldHaveRole(....; 

The application then cancels those rules and replaces them in its own provider.

public function boot() {
  // Cancels out the current rules
   HeyMan::forget()->aboutRoute('myPackageRoute');
  // Add new rules by package user.
   HeyMan::whenYouHitRouteName('myPackageRoute')-> ... 
}

The mechanism is route-name based, with whenYouHitRouteName and the forget call scoped with aboutRoute. So the package author declares an intent for a named route, and the application can retract exactly that rule and substitute its own.

This is the difference between the two models in one paragraph. A check written inline in a controller belongs to that controller and cannot be replaced from elsewhere, while a named rule in a provider can be withdrawn by anyone who can boot a provider. If your application depends on a vendor package that ships its own ACL, this override path is the reason to adopt HeyMan at all.

The syntax is verbose by default and the aliases are the fix

The README spends a moment anticipating the objection that you would have to memorise a long list of methods, and answers it twice. It says no cheat sheet is needed, and that IDE auto-completion is fully supported.

That answer works, but it also concedes the real cost. The default vocabulary is long by design, whenYouHitRouteName and youShouldHaveRole and whenYouMakeView and youShouldBeGuest are words, not verbs on a short method. The alias feature exists precisely because of that, letting a team rename the situations and conditions in the boot method to something like view or beGuest.

Aliases carry a cost too. Once you rename them, the code in your provider stops matching the package documentation and any search results, and a teammate reading the README will not find your method names. The decision is a team convention, so it belongs in the boot method where the README puts it and nowhere else.

One more design detail: the README says the package is integrated with laravel-debugbar out of the box, which fits the overall approach of keeping the rules visible and changeable in one place rather than hidden behind middleware you have to instrument.

Installation with composer and the version floor to check

Installing the package is a single composer command.

composer require imanghafoori/laravel-heyman

After that, the README's instructions amount to placing the calls in a service provider boot method, usually AuthServiceProvider.php, and importing the facade. There is no migration command, no seeding step and no configuration publishing step in the README, even though the repository does contain a config/ directory alongside src/ and tests/.

The requirements are listed plainly: PHP v7.0 or above and Laravel v5.1 or above. Those floors are permissive, and they are the numbers on the README rather than the reality of the tagged releases, which matters because of the next section.

The repository layout supports the claim that this is a real package rather than a snippet collection. There is composer.json, a phpunit.xml.dist test configuration, src/ for the implementation, config/ for configuration, tests/ for the suite, a .scrutinizer.yml for quality analysis and a .styleci.yml for code style, plus .github/ workflows for imports and tests.

v2.2.58 is the newest tag and the last push was on 2026-05-30

The release tags tell a specific story about which Laravel versions the package is actually installed on. Version 2.2.53 is labelled for install on Laravel 9 and is dated 2022-01-30. Version 2.2.55, labelled for install on Laravel 10, is dated 2023-02-14. Version 2.2.58, labelled as installable on Laravel v11, is dated 2024-03-02.

Read in order, that is one Laravel major per release, roughly a year apart, with the newest tagged release covering Laravel 11. There is no tag in the list for Laravel 12.

The licence field on the repository says MIT, so the code can be reused under permissive terms without copyleft obligations on applications that depend on it.

On maintenance, the repository is not archived and the last push was on 2026-05-30. That is inside the six month window from today, but the gap between that commit and the newest release tag is more than a year, and the README itself describes the package as continuing where other role and permission packages left off. The honest reading is that the repository is still receiving commits while the released versions track Laravel majors on an annual cycle, so the version you install and the code in the default branch are not the same thing.

Editorial conclusion

laravel-heyman fits Laravel applications whose access rules are numerous, central and shared between several packages, especially where vendor routes need rules you can override from your own provider. It does not fit a small application with a handful of checks, where the indirection of a facade chain costs more than it saves, and adopting it means accepting a package whose newest tagged release, v2.2.58, is described as installable on Laravel 11. Before installing it, check your Laravel version against those release notes, read the rules in the council repository's AuthServiceProvider.php as the working example, and confirm your editor resolves the facade alias before you commit to the verbose method names.

Frequently asked questions

Official sources

1. imanghafoori1/laravel-heyman on GitHub
2. Issues
3. License: MIT
4. README
5. Releases