Support Laravel Package

Getting Started

smorken/support is a grab-bag "support" package: a home for helpers, traits, and small utilities that a single developer didn't want to duplicate across projects. Treat it as a source of copy-paste-able patterns first and a dependency second.

1. Pull it in. It is not on Packagist, so add the VCS repository explicitly and pin a reference (there are no meaningful release tags to lean on):

"repositories": [
    { "type": "vcs", "url": "https://bitbucket.org/scott_morken/support.git" }
],
"require": {
    "smorken/support": "dev-master#<commit-sha>"
}

2. Confirm discovery. Check composer.json inside the package for extra.laravel.providers. If a provider is declared it will be auto-discovered; if not, register it manually in bootstrap/providers.php (Laravel 11+) or config/app.php.

3. Read src/ before anything else. There is effectively no documentation surface here. The authoritative spec is the directory listing:

ls -R vendor/smorken/support/src
cat vendor/smorken/support/composer.json   # autoload map tells you the namespace

Look specifically for a Providers/ directory (what gets bound or published), a Helpers/ or helpers.php file (globally-loaded functions — check autoload.files), and any Traits/ folder (the most reusable part).

4. First use case. Pick the smallest, lowest-risk unit — usually a single trait or a formatting helper — and prove it in a throwaway route or a Blade view before touching production models:

// routes/web.php, temporary
Route::get('/_probe', fn () => dd(
    class_exists(\Smorken\Support\...::class),
    function_exists('your_guessed_helper_name')
));

That one probe tells you whether autoloading and provider registration actually worked, which is where most of the friction lives.

Implementation Patterns

Traits on Eloquent models. Small support packages are usually thin on service providers and heavy on traits — scopes, casts, slug/status behaviour. Compose them rather than extending a package base model:

use Smorken\Support\Traits\HasSomething;

class Post extends Model
{
    use HasSomething;
}

Keep traits at the edge of the model. If a trait drags in a container dependency, wrap it in your own repository/service so the model stays testable.

Helpers in views and controllers. Global helper functions (loaded via autoload.files) are the most common payload. Use them where they remove noise — Blade conditionals, formatting — and avoid them in domain code where an injected service would be clearer:

{{-- fine --}}
{{ format_something($post->value) }}

{{-- prefer DI in application code --}}
public function __construct(private Formatter $formatter) {}

Config-driven behaviour. If the package ships config/*.php, publish it and diff it against the vendor copy so you know what knobs exist:

php artisan vendor:publish --provider="Smorken\Support\...ServiceProvider" --tag=config

Then move anything environment-dependent into config/ on your side, not into .env directly — a package with no documented config is a package whose env keys you can't safely guess.

Wrapping rather than scattering. Because dependents are zero and maintenance is uncertain, the durable pattern is to put a thin adapter over the package in your own app (app/Support/...) and call the adapter everywhere. Swapping out or vendoring the package later becomes a one-file change:

namespace App\Support;

class Slugger
{
    public static function make(string $value): string
    {
        return \Smorken\Support\...::slug($value); // single seam
    }
}

Composition in service providers. If the package registers macros (Collection, Str, Request), you'll normally want to add your own alongside them in AppServiceProvider::boot() so project-specific behaviour and package behaviour live in the same place and boot in a predictable order.

Gotchas and Tips

Bitbucket VCS requires credentials in CI. composer install on GitHub Actions/GitLab will fail with a 404, not a 403, when the deploy key or COMPOSER_AUTH token is missing. Set COMPOSER_AUTH with a Bitbucket app password or mirror the repo internally.

Pin to a commit SHA, never dev-master. With no tags and no dependents, there is no ecosystem pressure keeping master stable. A SHA pin is the only reproducible install, and Composer will happily keep the stale lock entry otherwise.

Global helper collisions. Functions loaded via autoload.files live in the global namespace. If the package doesn't guard with if (! function_exists(...)), a same-named helper in app/helpers.php becomes a fatal redeclare — and the failure surfaces at boot, not at call time. Grep for the function names before adding your own.

Auto-discovery silently not running. Packages cached in bootstrap/cache/packages.php from a previous composer install can mask a provider that was added later. When bindings "don't exist", run composer dump-autoload and php artisan package:discover before debugging anything else.

Config caching eats unpublished config. php artisan config:cache will freeze defaults you never published. Publish first, then cache — and re-run config:clear whenever you upgrade the SHA.

Boot-order dependencies. If the package's provider touches the DB, registers routes, or reads config in register() that another provider sets, ordering matters. Put manual registrations after framework providers in config/app.php and prefer lazily resolving anything ambiguous.

Debugging with no docs. Use reflection to enumerate what's actually there instead of guessing:

php artisan tinker
>>> array_map(fn($c) => $c->getName(), (new ReflectionClass(\Smorken\Support\...ServiceProvider::class))->getMethods());

Bus-factor risk — vendor it if it's load-bearing. Zero stars, zero dependents, single author, Bitbucket-only. If more than a couple of call sites depend on a specific helper, copy that file into app/Support/ with attribution and an upstream SHA comment. You keep the behaviour, drop the supply-chain and auth friction, and stop worrying about whether the repo disappears.

Extension point to prefer. Where the package exposes no events or interfaces, your own adapter layer is the extension point. Don't monkey-patch vendor files — an unmaintained package plus local edits is unrecoverable at the next upgrade.