Helpers

Helpers — traits and helper services

OrangeHRM has a lot of helpers scattered across the core plugin. The naming convention is consistent: most are use-able traits, and each trait typically wraps one helper service. Before writing a util function, check this catalog — the answer is usually "already exists."

This skill is a reference catalog. Each entry shows what to use, what method(s) it exposes, and the common case. For deeper documentation on specific helpers, see the linked skill.

How the trait pattern works (recap)

The codebase consistently uses traits as the DI access layer:

class MyClass
{
    use DateTimeHelperTrait;        // ← gives $this->getDateTimeHelper()
    use TextHelperTrait;            // ← gives $this->getTextHelper()
    use UserRoleManagerTrait;       // ← gives $this->getUserRoleManager()

    public function doSomething(): void
    {
        $now = $this->getDateTimeHelper()->getNow();
        $clean = $this->getTextHelper()->strip(...);
    }
}

Traits typically delegate to the DI container or instantiate the helper lazily. Same pattern in services, decorators, subscribers, commands, endpoints, validators — everywhere. See services skill for the full pattern.

Core helper services + their traits

These are the "everyday" helpers — formatters, normalizers, cross-cutting utilities. Each has a service class in orangehrmCorePlugin/Service/ and a matching trait in orangehrmCorePlugin/Traits/Service/.

Plugin-specific service traits (representative)

Every plugin has its own Traits/Service/<Name>ServiceTrait.php for each of its services. The pattern is universal — see services skill. Most-frequently used from outside their owning plugin:

When pulling in a cross-plugin service, you use that plugin's trait. The dependency between plugins is fine; the trait keeps consumers from instantiating the service directly.

Framework-level traits (no separate service)

Most of these wrap framework-provided objects (event dispatcher, logger, cache, validator) rather than OHRM-specific services.

Authentication / authorization traits

Doctrine / ORM traits

Already covered in detail in daos skill:

Controller / module traits

Encryption / security traits

See the security-primitives skill for the full treatment. Quick references:

Plain Helper/ classes (not traits)

orangehrmCorePlugin/Helper/ has a few non-trait helpers — instantiate with new or accessed via a service.

Utility/ plain classes

orangehrmCorePlugin/Utility/ has security and infrastructure utilities. Mostly covered in other skills:

"Is there a helper for…" cheat sheet

If your need isn't in the table: search src/plugins/orangehrmCorePlugin/Traits/ and Traits/Service/ for matching trait names. The naming is predictable — XHelperTrait, XServiceTrait. If nothing exists for the operation you need, the right answer is to add a helper service + trait, not to inline the logic in a feature.

When to add a new helper

A new helper is justified when:

1. The same logic appears in two places already (3rd time = definitely extract). One-off logic stays inline.
2. The logic is non-trivial — formatting, parsing, computation worth more than 5 lines.
3. It needs DI — accessing config, the EM, the dispatcher, etc. Goes in a service; trait wraps it.
4. It's pure — no I/O, no state. Goes in a static utility class or a plain helper.

Adding a new helper service + trait

Mirror an existing example like TextHelperService / TextHelperTrait:

// src/plugins/orangehrmCorePlugin/Service/SlugHelperService.php
namespace OrangeHRM\Core\Service;

class SlugHelperService
{
    public function slugify(string $input): string
    {
        return strtolower(preg_replace('/[^a-z0-9]+/i', '-', trim($input)));
    }
}

// src/plugins/orangehrmCorePlugin/Traits/Service/SlugHelperTrait.php
namespace OrangeHRM\Core\Traits\Service;

use OrangeHRM\Core\Service\SlugHelperService;

trait SlugHelperTrait
{
    protected ?SlugHelperService $slugHelper = null;

    public function getSlugHelper(): SlugHelperService
    {
        if (!$this->slugHelper instanceof SlugHelperService) {
            $this->slugHelper = new SlugHelperService();
        }
        return $this->slugHelper;
    }
}

For pure helpers like this, no container registration is needed — the trait instantiates on demand. For helpers that need DI (config, EM, dispatcher), follow the services skill's full registration pattern.

Recipes

Recipe 1 — Service that uses several common traits

namespace OrangeHRM\X\Service;

use OrangeHRM\Core\Traits\EventDispatcherTrait;
use OrangeHRM\Core\Traits\LoggerTrait;
use OrangeHRM\Core\Traits\Auth\AuthUserTrait;
use OrangeHRM\Core\Traits\Service\ConfigServiceTrait;
use OrangeHRM\Core\Traits\Service\DateTimeHelperTrait;
use OrangeHRM\Core\Traits\Service\TextHelperTrait;
use OrangeHRM\Core\Traits\UserRoleManagerTrait;

class WidgetService
{
    use EventDispatcherTrait;
    use LoggerTrait;
    use AuthUserTrait;
    use ConfigServiceTrait;
    use DateTimeHelperTrait;
    use TextHelperTrait;
    use UserRoleManagerTrait;

    public function buildSlug(string $name): string
    {
        $clean = $this->getTextHelper()->stripTags($name);
        return strtolower(preg_replace('/[^a-z0-9]+/i', '-', $clean));
    }

    public function logOperation(string $operation): void
    {
        $this->getLogger()->info(sprintf(
            '[%s] User %d: %s',
            $this->getDateTimeHelper()->getNow()->format('Y-m-d H:i:s'),
            $this->getAuthUser()->getUserId(),
            $operation,
        ));
    }

    public function getAccessibleWidgets(): array
    {
        if (!$this->getConfigService()->isWidgetFancyModeEnabled()) {
            return [];
        }
        return $this->getUserRoleManager()->getAccessibleEntityIds(Employee::class);
    }
}

The bigger the service, the more traits it composes — that's fine. The trait list is the service's dependency declaration. Reading from the top quickly tells you what it depends on.

Recipe 2 — Add a new helper

Goal: a MoneyHelperService for formatting currency strings consistently.

namespace OrangeHRM\Core\Service;

class MoneyHelperService
{
    public function format(float $amount, string $currencyCode = 'USD'): string
    {
        return $currencyCode . ' ' . number_format($amount, 2, '.', ',');
    }
}

namespace OrangeHRM\Core\Traits\Service;

use OrangeHRM\Core\Service\MoneyHelperService;

trait MoneyHelperTrait
{
    protected ?MoneyHelperService $moneyHelper = null;

    public function getMoneyHelper(): MoneyHelperService
    {
        return $this->moneyHelper ??= new MoneyHelperService();
    }
}

Now any class can use MoneyHelperTrait and call $this->getMoneyHelper()->format($amount, $currency). No further registration needed — pure helper, no DI dependencies.

Recipe 3 — Pick the right trait by responsibility

The mental model: think about what you're doing, then pick the matching trait.

• "Format a date for the UI" → date formatting → DateTimeHelperTrait
• "Log that this happened" → logging → LoggerTrait
• "Send an event so other plugins can react" → events → EventDispatcherTrait
• "Check if the user is allowed to do this" → permissions → UserRoleManagerTrait + see authorization
• "Encrypt this before saving" → encryption (entity listener) → EncryptionHelperTrait + see security-primitives
• "Read a feature flag" → config → ConfigServiceTrait + see config
• "Run a DQL query" → ORM → EntityManagerHelperTrait + see daos

If you find yourself doing two of these at once, you use two traits. The trait list grows with the class's responsibilities. That's normal — services routinely use 4-8 traits.

Checklists

Before writing a new helper

• Search Traits/ and Traits/Service/ in orangehrmCorePlugin for matching trait names
• Search the "Is there a helper for…" cheat sheet above
• Check other plugins' Traits/Service/ — sometimes a plugin owns a helper that's broadly useful
• Only if nothing exists, add a new helper service + trait — mirror existing pattern from TextHelperService or similar

Compose helpers into a class

• use <Helper>Trait; at the top of the class
• Call $this->get<Helper>() to access the helper service
• Need multiple? List them all — no upper limit, services routinely use 4-8 traits

Add a new helper service + trait

• Service class in src/plugins/orangehrm{X}Plugin/Service/<Name>HelperService.php
• Matching trait in Traits/Service/<Name>HelperTrait.php with ?<Name>HelperService $field and lazy get<Name>Helper() method
• If the helper needs DI (config, EM, dispatcher) — register in plugin's PluginConfiguration::initialize() and have the trait fetch from the container instead of new-ing
• If pure (no DI), the lazy new is fine — no container registration needed
• Add a row to your project's "Is there a helper for…" table so future devs find it

Things that bite

• Don't bypass the trait and instantiate helpers directly with new ConfigService(). Some traits cache the service per-class; bypassing means an extra instantiation per call. More importantly, it breaks the convention — other devs look for use ConfigServiceTrait and don't find it.
• Don't put business logic in a helper — helpers are utilities (formatters, normalizers, lookups). Business logic that involves the domain belongs in a Service (see services skill).
• AuthUserTrait only works inside a request lifecycle. In console commands or migrations, the session isn't bound — getAuthUser()->getUserId() returns null. Either pass a user ID as a command argument or work without one.
• getEntityManager() is fine in any context that's run after Framework is bootstrapped (which is everywhere except very early install bootstrap). Use it freely.
• use-ing two traits with the same method name is a fatal error in PHP. Rare here because OHRM trait method names are distinctive, but if you ever see Trait method getX has not been applied, you've got a name collision — rename one of the methods.
• Helpers are stateless. Don't store request-specific data on a helper service — different callers might share the same instance. If you need request state, use the service itself, not a helper.
• ServiceContainerTrait is internal plumbing — don't use it directly from feature code. Use the higher-level traits that wrap container access.