Common Laravel Package

Getting Started

composer require ibrand/common
composer show ibrand/common   # confirm the version you actually got

Before writing a single line against it, open vendor/ibrand/common/composer.json and read three keys: require (which illuminate/* versions it supports), autoload.psr-4 (the real root namespace), and extra.laravel (whether a service provider/aliases are auto-discovered). If the package is not on Packagist, add it as a VCS repository instead:

"repositories": [{ "type": "vcs", "url": "https://github.com/guojiangclub/common" }]

Then walk the src/ tree in this order, which is the usual layout for a "common classes and services" package:

1. src/*ServiceProvider.php — what it binds, merges, publishes, and registers.
2. src/helpers.php or a Support/ directory — global functions are the most common thing to collide.
3. src/Traits/, src/Models/ — these are what you will actually reuse daily.
4. src/Services/, src/Contracts/ — the injectable behaviour and its interfaces.

First use case: treat this as a shared baseline library, not a framework. The realistic first win is pulling a base model / trait (common scopes, UUIDs, audit columns) or a response/service wrapper into a new app so you do not re-copy it from a sibling project. Wire it up and prove it works with one throwaway route or a tinker session:

php artisan vendor:publish --provider="Ibrand\Common\CommonServiceProvider"
php artisan tinker
>>> app(\Ibrand\Common\CommonServiceProvider::class);   // resolves or throws

Because the package has essentially no community footprint (2 stars, 0 dependents), the source is the documentation. Budget an hour to read it end to end before the first commit that depends on it.

Implementation Patterns

Wrap it, never sprinkle it. The highest-value pattern with a low-signal package is a thin application-level adapter so the vendor namespace appears in exactly one place:

namespace App\Support;

use Ibrand\Common\Services\SomeService;

class SharedThings
{
    public function __construct(private SomeService $inner) {}

    public function doThing(array $payload): mixed
    {
        return $this->inner->handle($payload);
    }
}

Bind it once ($this->app->bind(SharedThings::class, ...)) and your controllers/models stay vendor-agnostic. When the package rots or you fork it, you change one file.

Traits on your own classes. If src/Traits/ ships model or controller traits, use them in your own base App\Models\Model or App\Http\Controllers\Controller rather than in dozens of leaf classes — it keeps the blast radius of an upgrade to a single parent.

Explicit provider registration. Auto-discovery depends on a well-formed extra.laravel block; when in doubt, register manually in bootstrap/providers.php (Laravel 11+) or config/app.php (older) and skip the guessing.

Pin and vendor-control it.

"require": { "ibrand/common": "1.2.*" }

Commit composer.lock. If you need a patch, fork to an internal namespace (yourorg/common) via a VCS repository entry and update the PSR-4 root — that is a ten-minute job and it removes the upstream bus factor entirely.

Testing. Bind fakes at the container level and assert through your adapter, not through the vendor class:

$this->mock(SharedThings::class, fn ($m) => $m->shouldReceive('doThing')->andReturn('ok'));

Add one smoke test that simply resolves every class the provider registers — that catches broken constructor signatures immediately after a Laravel upgrade.

Config-driven behaviour. If the package merges config, read the merged result (config('...')) rather than assuming defaults, and drive environment-specific values from .env through your own config/ file.

Gotchas and Tips

• Maintenance risk is the headline. 2 stars, 0 dependents, one vendor. Assume no security patches and no Laravel 12 support until you verify composer.json constraints. Treat the source as a reference implementation you may end up owning.
• Global helper collisions. Packages that autoload files: ["src/helpers.php"] define bare functions. If they lack if (! function_exists(...)) guards, a second package (or your own helpers) can fatal at boot with "cannot redeclare". Grep for function in the package before installing alongside another helper library.
• Auto-discovery silently failing. If nothing works, check php artisan package:discover output, then php artisan config:clear && composer dump-autoload. A stale bootstrap/cache/packages.php is the usual culprit.
• Publish tags and filename clashes. Use php artisan vendor:publish --provider="..." --tag=config and diff the published file against the vendor copy; don't blindly overwrite a config name that already exists in your app.
• Namespace mismatch. Old packages sometimes declare Ibrand\Common in code but ibrand\common in PSR-4, or have stray classmap entries. composer dump-autoload -o will surface it; class_exists() in tinker confirms.
• Deprecated Laravel APIs. Look for str_*/arr_* helpers, $app->bind string bindings, and facades removed in Laravel 9/10/11. These fail loudly at runtime, not at install — which is exactly why the resolve-everything smoke test matters.
• Hidden schema assumptions. Shared model traits often presume specific columns (deleted_at, created_by, uuid). Read the trait's boot* methods before applying it to an existing table, and migrate the columns in the same PR.
• Extension points, in order of preference: publish config → bind an override in the container → extend the class and swap the binding → fork. Never edit vendor/.
• Debugging: php artisan about for provider state, php artisan tinker for app()->make() checks, and composer why ibrand/common when an unexpected transitive dependency drags it in.
• If you only need 50 lines of it, copy those lines behind your own namespace and drop the dependency. With this dependency profile, that is often the more defensible engineering decision.