Normalize helper surface: remove dead helpers, move router metadata access into Request, and trim redundant proxies #462

Summary

Clean up the framework helper surface with a stricter distinction between:

• dead internal helpers that should be removed
• internal router metadata access that should move behind Request proxy methods
• public convenience helpers that may remain as part of the framework DX
• trivial proxies that may be deprecated or removed only when that improves the API overall

This issue is not only about deleting unused functions. It is about making helper usage intentional and reducing direct coupling to router internals.

Goals

• Remove helpers that are truly dead and not part of the intended public API
• Refactor router-related internal access behind request() / Request proxy methods
• Migrate core framework usage to the new Request methods where appropriate
• Keep developer-facing helpers that still provide meaningful convenience
• Avoid removing public API only because current in-repo usage is low

Scope

1. Remove Dead Internal Helpers

These appear to be internal-only and provide no meaningful public DX:

• get_caller_class()
• get_caller_function()

If verification confirms no downstream/template reliance, they can be removed directly with tests updated accordingly.

2. Refactor Router Metadata Access Into Request

Router helpers that expose matched-route metadata should no longer be the primary internal access path.

This issue should add or standardize Request proxy methods for router metadata such as:

• current module
• route prefix
• route group existence
• module base namespace
• route name
• route params / single param
• route URI
• route method
• route cache settings
• current controller / action / callback where still justified

The exact method names should follow existing Request naming conventions.

Examples of target direction:

request()->getRouteName();
request()->getRouteParam('id');
request()->getRouteUri();
request()->getCurrentModule();
request()->getRoutePrefix();

3. Migrate Core Internal Usage

Update core framework code to use request() / Request proxy methods instead of reading route metadata through global router helpers.

This includes currently active core usages such as:

• current_module()
• route_prefix()
• route_group_exists()
• module_base_namespace()
• any other router helper still used in src/

Templates may be updated where appropriate, but template usage should be treated as real consumer usage, not ignored.

4. Review Public Convenience Helpers

Low usage alone is not enough reason to remove a helper.

Helpers should be kept if they are part of the intended developer-facing API and improve readability in controllers, views, templates, or middleware.

Likely keep-or-discuss explicitly:

• route_name()
• route_param()
• get_referrer()
• current_url()
• logger helpers such as error(), warning(), notice(), info(), debug()

For these helpers, choose one of:

• keep as supported public API
• deprecate with replacement path
• remove only after migration and explicit decision

5. Trivial Proxy Cleanup

Some helpers are thin proxies over equally clear method calls, for example:

• export() -> VarExporter::export()
• get_user_ip() -> server()->ip()
• route_method() -> request()->getMethod()
• route_uri() -> request()->getUri() or equivalent proxy method

These should be evaluated individually, not removed by blanket rule.

Removal is appropriate only when:

• the replacement is stable and clearer
• internal usages are migrated
• template/project impact is understood
• test coverage is updated

Acceptance Criteria

• Dead internal helpers are removed
• Router metadata access used by core is available via Request proxy methods
• Core framework usage is migrated away from direct router helper access where applicable
• Public helper API is explicitly classified as kept, deprecated, or removed
• Templates and scaffolded modules are treated as supported consumers during the review
• PHPUnit suite passes
• PHPStan passes
• Code style checks pass

Out of Scope

• unrelated helper refactors not connected to this cleanup
• larger architectural changes outside helper normalization
• removal of public convenience helpers without explicit API decision