Helpers Laravel Package

Getting Started

This is an internal, zero-documentation package — the Description is still the composer.json placeholder and there are no stars or dependents to learn from. Treat the source as the only spec.

1. Add the private repository to composer.json (the host is not Packagist):

   {
     "repositories": [
       { "type": "vcs", "url": "https://git.velcoda.tools/telebutler/packages/helpers.git" }
     ],
     "require": { "velcoda/helpers": "dev-main" }
   }
   

   Ensure your CI runner and every developer has credentials for git.velcoda.tools (SSH key or HTTPS token in COMPOSER_AUTH / ~/.composer/auth.json). Without this, composer install fails for the whole team.

2. Read composer.json first. The decisive line is the autoload block. A "helpers" package almost always ships "files": ["src/helpers.php"] rather than a classmap, which means the functions are loaded globally on every request before your app boots. Note the exact path, then read that file top to bottom — that file is the package.

3. Check for a service provider. If extra.laravel.providers is present, Laravel auto-discovers it. If not, and you find bindings or config in src/, register it manually in config/app.php.

4. Verify it actually loaded:

   composer dump-autoload
   php artisan tinker
   >>> function_exists('the_helper_you_found')
   

   If false, grep vendor/composer/autoload_files.php for the package path — that file is the authoritative record of what was included.

5. First use case: take the single helper you need, call it in tinker with representative input (empty string, null, an Eloquent model, a Carbon instance), and confirm the output shape before it touches a controller. Because there are no tests, your tinker session is the only documentation you will get.

Implementation Patterns

Call it directly, but from one place. Global helper functions are convenient but diffuse. In a codebase using this package, the most maintainable pattern is to call the helper inside a thin, namespaced wrapper you own:

// app/Support/Phone.php
final class Phone
{
    public static function normalize(?string $value): ?string
    {
        return $value === null ? null : normalize_phone($value); // package helper
    }
}

Then Blade, controllers, and jobs reference Phone::normalize(). If the package is abandoned or a function is renamed upstream, you change one file instead of grepping the whole app.

Blade usage is the natural fit. Helpers of this kind are usually designed for templates — formatting a number, truncating a label, converting a timezone. Use them directly in Blade for presentation-only concerns; keep anything that affects persisted data behind your wrapper.

Use them in validation and form requests. A helper that sanitizes a phone number or slug is best applied in prepareForValidation() so the normalized value is what the validator and the database both see.

Characterization tests, not unit tests. You cannot test the package's internals meaningfully, but you can pin its behavior:

public function test_phone_helper_shape(): void
{
    $this->assertSame('+15551234567', Phone::normalize('(555) 123-4567'));
}

Write these for each helper you rely on. They are your regression alarm when you bump the dependency — and the only spec that exists.

Pin to a commit, not a branch. With no tags, dev-main can change under you between deployments. Use "dev-main#<sha>" or a repositories path/vcs entry locked to a specific commit, and bump deliberately.

Job and queue safety. If a helper returns a Carbon instance, a closure, or a model, verify it survives serialization. Global-function helpers frequently return Carbon implicitly (e.g. now()-style wrappers) which is fine, but a returned closure or resource is not.

Gotchas and Tips

• Global namespace collisions are the #1 failure mode. A helpers.php loaded via autoload.files is included before the framework's own helpers in some setups. If the package defines str_limit, array_get, or anything Laravel already declares, PHP throws a fatal "Cannot redeclare function" — and the stack trace points at Composer's autoloader, not the package. Check that every function in src/helpers.php is guarded with if (! function_exists('...')). If it is not, patch it in a fork; you cannot fix it from your app.

• Fatal errors bypass Laravel's error handler. A redeclare or syntax error in autoload.files kills the request before the exception handler exists, so you get a white screen or a raw PHP error rather than an Ignition page. When the app dies with no logs, suspect this package first and run php -l vendor/velcoda/helpers/src/helpers.php.

• Opcache / autoload cache. Editing the package inside vendor/ has no effect until composer dump-autoload (and sometimes php artisan optimize:clear). Better: use a Composer path repository with a symlink during development so your edits are live.

• No types means static analysis noise. Un-annotated global functions produce Cannot determine return type and Call to an undefined function in Larastan/PHPStan. Either add a stubs/ directory with function signatures and register it via phpstan.neon scanFiles, or exclude the helpers from analysis — but do not simply ignore the errors, since a typo'd function name is a runtime fatal, not a caught exception.

• Private repo auth in CI is the most common onboarding blocker. Put the token in COMPOSER_AUTH as a JSON env var rather than committing auth.json. Cache ~/.composer/cache in CI to avoid re-cloning on every build.

• Check for config and env coupling. If src/ contains a config/ directory, run php artisan vendor:publish --tag=... and diff the published file against your .env. A helper that reads env() directly (rather than config()) will silently return null once php artisan config:cache runs in production — a classic "works locally, breaks deployed" bug.

• Extension points are minimal by design. Global-function packages have no interfaces or bindings to swap. That is precisely why the wrapper-class pattern above matters: it is the only seam you get.

• Treat it as unmaintained. Score 0, no stars, no dependents, and a placeholder description signal an internal package that exists to deduplicate a few functions across the Telebutler estate rather than a supported library. Budget for it being vendored or inlined into your app eventually — keep usage behind your wrapper so that migration is a mechanical delete rather than a refactor.