Common Laravel Package

Getting Started

The package ships with no meaningful README and hasn't been tagged since April 2017, so the first job is inventory, not integration. Treat the source as the documentation.

1. Install and inspect before you write any code

composer require ideasbucket/common
composer show ideasbucket/common          # version, PHP constraint, deps
find vendor/ideasbucket/common -name '*.php' | sort

Read vendor/ideasbucket/common/composer.json first — it tells you the PHP version the author targeted (almost certainly 5.6/7.0), the PSR-4 namespace root, and whether there's a extra.laravel block for package auto-discovery. On a modern Laravel app (10/11/12, PHP 8.2+) expect the constraint to conflict; you'll need --ignore-platform-reqs or a fork.

2. Register it manually if there's a service provider

A 2017-vintage package likely predates Laravel auto-discovery. Check config/app.php providers array conventions and add the provider by hand if extra.laravel.providers is absent. If there is no provider at all, the package is pure PHP and needs zero Laravel wiring — just the autoloader.

3. First use case: consolidate scattered helpers

The realistic day-one win for a "common" package is replacing copy-pasted app/Helpers/functions.php utilities. Grep your own codebase for hand-rolled array/string/date helpers, then check whether the package covers the same ground:

grep -rn "function " vendor/ideasbucket/common/src | head -50

If the package's helpers overlap with what you already have, the decision is usually "keep ours" — you gain nothing by swapping a maintained internal helper for an unmaintained external one. Where it wins is genuinely reusable primitives you haven't written (e.g. a slugifier, an array dot-notator) that save you a dependency.

Where to look first: src/ for concrete classes, tests/ if present (it's the only reliable usage documentation), and the git history on the repo for what the author actually intended the API surface to be.

Implementation Patterns

Wrap, don't sprinkle. Never call IdeasBucket\Common\... directly from controllers or Blade. Put a thin adapter in your own namespace so you can swap the implementation later:

namespace App\Support;

class Str
{
    public static function slug(string $value): string
    {
        return \IdeasBucket\Common\Str::slugify($value);
    }
}

Given the package's age and zero dependents, assume you will replace it within a year. The adapter is what makes that a one-file change instead of a hundred.

Traits go on models and services, not controllers. If the package ships traits (common for Common packages — timestamp helpers, array-access, toArray behaviour), apply them to Eloquent models or base service classes. Test immediately that they don't collide with Model methods:

class Post extends Model
{
    use \IdeasBucket\Common\Traits\HasCommonBehaviour;
}

Trait method collisions surface at class-load time, so a single php artisan tinker instantiation will tell you whether it's safe.

Use it in console commands and jobs, not request paths. Legacy utility code often has untyped signatures and loose comparisons. In a queued job the blast radius of a bad return type is contained; in a controller it's a 500 for the user. If you must call it in a request, wrap the call in a try/catch and coerce the return type at the boundary.

Value objects / DTOs are the best fit. If the package exposes immutable value objects (money, email, uuid), that's where it earns its keep — they're hard to write correctly and easy to verify. Instantiate them at the edge of your domain and convert to primitives before persistence.

Testing pattern. Because there are no docs, your test suite becomes the documentation. Write a small characterization test per class you actually use, capturing real return values:

public function test_slug_behaviour(): void
{
    $this->assertSame('hello-world', Str::slug('Hello World!'));
    $this->assertSame('hello-world', Str::slug('  Hello   World  '));
}

That test file is your upgrade safety net and the reference your team will actually read.

Integration tip: pin an exact version in composer.json ("ideasbucket/common": "1.0.0" rather than ^1.0). With no maintainer activity, an unexpected tag is more likely to be a compatibility break than a fix.

Gotchas and Tips

It is effectively abandoned. Last release April 2017, one star, zero dependents, no issue traffic. Budget for the possibility that you are the maintainer now. If the value is real, fork it to your org, add PHP 8 type declarations and a CI matrix, and require the fork via a VCS repository entry. That is usually cheaper than fighting --ignore-platform-reqs forever.

PHP 8 will break untyped legacy code. Expect implicit nullable parameters (string $x = null) to emit deprecations, and loose == comparisons against null/0/'' to behave differently than the author intended. Run php -d error_reporting=E_ALL against your characterization tests and fix forward in a fork rather than suppressing.

No auto-discovery is the silent failure mode. If a class-not-found error appears despite a successful composer require, the cause is nearly always: (a) the package has no service provider and you assumed one, (b) a composer dump-autoload was skipped after a manual repositories edit, or (c) the PSR-4 namespace root in composer.json doesn't match the directory layout. composer dump-autoload -o then composer show -a ideasbucket/common resolves it 90% of the time.

Global helper functions are a collision risk. If the package defines functions in the global namespace (common for 2017-era "common" packages), they can fatally collide with Laravel's own str(), array_get(), or with another package. Check for function_exists guards in the source before adding a second utility package.

No type declarations means static analysis noise. PHPStan/PHPStan-level-5 will flag every call into this package as mixed. Either add a stub file or write your adapter with explicit return types and assert()/cast at the boundary — otherwise the package's untyped returns infect your whole call graph.

Config quirks. If there's a config/ directory, it almost certainly isn't publishable via vendor:publish without a registered provider. Copy the defaults into your own config file and inject them, rather than relying on the package's config merge.

Extension points are thin — plan to fork, not extend. With no interfaces or abstract base classes typical of this era, subclassing is fragile. Wrap (adapter pattern), don't extend. When the day comes to replace it, your adapter surface tells you exactly which five methods you need to reimplement — usually against illuminate/support, ramsey/uuid, or nesbot/carbon, all of which are maintained and already in your dependency tree.

Security posture. An unmaintained package receiving no security patches is a supply-chain consideration. Before adopting, run composer audit and confirm the package has no transitive dependencies of its own that are also stale. If it has zero dependencies and is pure functions, the risk is low; if it pulls in a 2017-era HTTP client, walk away.