Download the PHP package coyote6/laravel-base without Composer

Laravel Base

A collection of small Laravel traits and helpers — mainly Eloquent model creation-time conventions (author/client/machine name/slug stamping), select-option helpers, and a couple of database/file utilities.

Installation

The service provider (Coyote6\LaravelBase\Providers\BaseServiceProvider) is auto-discovered and merges this package's config under the coyote6-base key automatically. Publishing is optional, only needed to override the defaults:

This publishes config/coyote6-base.php into your application.

Upgrade From 0.2.7

v0.3.0 is a breaking release. See CHANGELOG.md for the full old-namespace → new-namespace table — every trait moved, and four were renamed (HasAuthor/HasClient/HasMachineName/HasMachineNameAsId → Author/Client/MachineName/MachineNameAsId). There's no deprecation shim; it's a hard cutover.

Those four new names are short and generic enough to routinely collide with a real domain class already living in an app being upgraded — Client and Author are common model names. So the upgrade command below always imports them aliased (BootAuthor/BootClient/BootMachineName/ BootMachineNameAsId) rather than bare, regardless of whether this particular file happens to collide today. This is specific to the automated upgrade path; a fresh install has no such history to protect against, so Creation Helpers below documents the plain, unaliased names as the default — alias by hand only if your own app also has a class by the same name.

Automating the namespace rename. This package ships a command that scans your application and rewrites old trait references to whatever the current version needs:

It scans app/ and database/ by default (comma-separate --path to scan somewhere else, e.g. --path=app,database,routes), then runs every upgrade step it knows about, one at a time — currently just the v0.2.7 → v0.3.0 rename below, but future breaking releases will add their own step here, so running this command again after a later update only applies whatever's actually new. Each step reports on its own:

Answer yes to write that step's changes, or no to leave them untouched and move on to the next step. Pass --apply to skip the prompt and write immediately instead — useful in CI or any other non-interactive context:

A step with nothing left to do prints No file changes found. and moves on without asking anything, so it's safe to re-run this command at any time, even after it's already been applied.

It rewrites both the use import statement and the bare use ShortName; trait-inclusion line inside a class body, for every renamed/moved trait — including an aliased import (use Coyote6\LaravelBase\Traits\HasAuthor as Whatever;), which keeps your alias and only swaps the underlying namespace. HasAuthor/HasClient/HasMachineName/HasMachineNameAsId are always rewritten aliased as BootAuthor/BootClient/ BootMachineName/BootMachineNameAsId, per the naming note above, even in files where the bare name wouldn't currently collide with anything — so the same trait always reads the same way everywhere in your codebase, and you never have to wonder why one file says Client and another says BootClient.

Two situations it can't safely handle automatically:

• *Even the `Bootalias collides with an existing, unrelated class already resolvable in that file** — either because the file already has its ownuse App\Models\BootClient;, or because the file lives in the same namespace as aBootClient` class and would resolve it there with no import at all. To prevent asking on every model, the command asks once per distinct trait/collision (not once per file) as the same collision typically repeats across every model using that trait in the same namespace:

  Answer with a different alias to apply it everywhere that collision occurs, or leave it blank to skip those files and list them under a "collide with an existing, unrelated class already resolvable" warning instead — everything else in an affected file still gets rewritten normally. This prompt is never asked under --apply; a still-conflicting rename is left untouched and reported instead, same as declining would do interactively.

• HasUuid has no direct replacement. Laravel's native Illuminate\Database\Eloquent\Concerns\HasUuids is a safe mechanical swap namespace-wise, but not a pure rename behaviorally — HasUuids generates ordered, time-sortable UUIDs by default, where HasUuid generated random ones. So it's never applied silently; the command asks once, the same way it does for a colliding alias:

  Answer yes to replace it everywhere HasUuid is found this step, or no to leave those files untouched and listed under a "has no direct replacement" warning instead, same as before. Never asked under --apply; it's left flagged and reported instead of assuming an answer.

Review the diff and run your own test suite before committing — this is a straightforward textual rewrite, not a full PHP-aware refactor, so give it a look rather than trusting it blindly on generated or unusually formatted code.

If your database columns don't match the new defaults. BootAuthor, BootClient, BootMachineName, BootMachineNameAsId, and Slug used to hardcode which attribute they read from/wrote to (author_id, client_id, machine_name, name). Those are now config-driven (field/reference under each section — see Configuration below), and the defaults match the old hardcoded names exactly, so most upgrades need no config changes at all. If any of your tables already used different column names for these before upgrading, publish the config and point field/reference at your existing columns instead of renaming the database.

Example below changes the default field name, author_id to user_id. This was hardcoded to 'author_id' before v0.3.0

machine_name's default generation method changed. Before v0.3.0, BootMachineName/BootMachineNameAsId always lowercased and replaced every non-alphanumeric character with an underscore — snake_case-shaped output. The new default is strictKebab (dash-separated), since that's now the package-wide default machine_name.method — see coyote6/laravel-str for what strictKebab and the other available methods actually do. If your existing machine_name values (or anything reading them) depend on the old underscore-separated format, publish the config and set machine_name.method explicitly to whichever option in the Method table matches what you already have — otherwise newly-created records will get dash-separated values alongside your existing underscore-separated ones.

The upgrade command surfaces this itself rather than leaving it to this paragraph: if this run's scan finds machine-name generation in use at all (under either the old or new trait name, so this still fires on a second run after the rename itself already landed), it checks whether coyote6-base's config is published yet, offers to publish it if not, then asks which machine_name.method this app should use — defaulting to whatever the config already has, so pressing enter keeps the current value:

Picking a different method updates the published config's machine_name.method line directly (a targeted text swap, not a full rewrite of the file, so the config's own per-method documentation comments are left alone). Never asked under --apply; it prints the same reminder instead and leaves the config untouched.

Upgrade From 1.0.0

v2.0.0 is a breaking release: every BootTraits convention method was renamed from its old create* verb to assign*...OnModelCreation, to make explicit that it assigns a value (unless one is already present) rather than creating anything, and that it fires on Eloquent's creating event.

Owner/User are new in this same release and already ship with the assign*OnModelCreation names — there's nothing to migrate for either.

Most apps should be unaffected as BootTraits calls these methods internally by name, so a model that only composes one of the Boot/* traits (never defining or calling the method itself) picks up the new name automatically, with no code changes needed. This only matters if your own code manually defines one of these methods (to opt into the BootTraits convention without using the trait), overrides one of these trait methods, or calls one directly.

The same php artisan coyote6-base:upgrade command documented above picks this up as its own step — re-running it after upgrading also runs Running v2.0.0 upgrades, renaming both the method definition and any -> call site, and leaving already-renamed code untouched (safe to run repeatedly). No deprecation shim ships for the old names.

Upgrade From 2.0.0

v2.1.0 deprecates the GetAsOptionsAbbr trait. GetAsOptions::getAsOptions() now takes a $key (plus $field, $limit, $page, $modifyQuery), so one trait covers an abbr-keyed list too — getAsOptions('abbr'). GetAsOptionsAbbr::getAsOptions() still works, now as a shim over getAsOptions('abbr') that raises an E_USER_DEPRECATED notice on every call, so nothing breaks the moment you upgrade — the migration can happen on your schedule.

The same php artisan coyote6-base:upgrade command handles it as its Running v2.1.0 upgrades step. For every model composing GetAsOptionsAbbr it swaps the trait for GetAsOptions (import and class-body use, keeping any as alias), and then across every scanned file — so point --path at everything that could call these models, e.g. --path=app,resources — it adds 'abbr' as the first argument to each no-argument Model::getAsOptions() call it can resolve to one of those models (imported, same-namespace, or fully qualified), plus any self::/static::/$this-> call in the model's own file. Idempotent and safe to re-run.

It deliberately leaves three things for you, reporting each with the file path:

• a model composing both GetAsOptions and GetAsOptionsAbbr (never valid — they declare the same method);
• a Model::getAsOptions(...) call that already passes arguments — $key is the first parameter now, so you decide whether 'abbr' belongs ahead of what's there;
• a ->getAsOptions() call on a variable, relation, or query result the tool can't resolve to a class.

Directory Structure

• src/Traits/Models/ — Traits meant to be used directly on Eloquent models: BootTraits, GetAsOptions, GetAsOptionsAbbr (deprecated), GetBySlug.
• src/Traits/Models/Boot/ — Creation-helper traits that provide the assign*OnModelCreation hook methods BootTraits looks for via method_exists(): Author, OriginalAuthor, Owner, User, Client, MachineName, MachineNameAsId, Slug, and the shared internal helper ResolvesMachineName. Always used alongside BootTraits on the model, never alone.
• src/Traits/Database/ — Traits meant to be used on service providers, migrations, or other database-related classes: DropsIndexes, ServiceProviderSeedsDb.
• src/Traits/Files/ — ReadsCsv, for reading a CSV file into an array.
• src/Upgrades/ — UpgradeStep (the interface every upgrade step implements), Upgrade_0_3_0 (the v0.2.7 → v0.3.0 step, see "Upgrade From 0.2.7" above), Upgrade_2_0_0 (the v1.0.0 → v2.0.0 step, see "Upgrade From 1.0.0" above), and Upgrade_2_1_0 (the GetAsOptionsAbbr → GetAsOptions migration, see "Upgrade From 2.0.0" above).
• src/Console/Commands/UpgradeCommand.php — the coyote6-base:upgrade Artisan command; runs every step registered in its own steps() method.
• src/Helpers/Helpers.php — Global helper functions (getCurrentUserId(), getCurrentUserClientId()), autoloaded on every request via composer's files autoload.
• src/Providers/BaseServiceProvider.php — Merges/publishes config/coyote6-base.php and registers coyote6-base:upgrade.
• config/coyote6-base.php — Configuration consumed by the Boot/* traits (see Configuration below).

Configuration

All config lives under the coyote6-base key. Every field/reference option is just the attribute name to read from or write to — override any of them per-application via the published config file.

machine_name.method always runs through Str::ascii() first, regardless of which method is selected. Allowed values: strictKebab (default), strictSnake, pureKebab, pureSnake, kebab, snake, dot, slug, studly, pascal, camel, lower, upper, deduplicate, transliterate — see the config file's own comments for per-method examples and parameters (machine_name.method_parameters).

Available Traits

Boot Method

Coyote6\LaravelBase\Traits\Models\BootTraits — registers Eloquent model-event listeners (creating, created, updating, updated, deleting, deleted) that call a matching convention method on the model if it exists: assignAuthorOnModelCreation, assignOriginalAuthorOnModelCreation, assignOwnerOnModelCreation, assignUserOnModelCreation, assignClientOnModelCreation, assignMachineNameOnModelCreation, assignSlugOnModelCreation on creating; modelCreating/modelCreated/modelUpdating/modelUpdated/modelDeleting/modelDeleted at their respective events. A model opts into any of this just by defining the method — directly, or via one of the Boot/* traits below — BootTraits itself never requires any of them to exist.

For UUID primary keys, use Laravel's native Illuminate\Database\Eloquent\Concerns\HasUuids trait — this package no longer ships its own Uuid method.

Creation Helpers (require BootTraits)

All under Coyote6\LaravelBase\Traits\Models\Boot:

• Author — sets author.field (default author_id) to the current user's id, unless already set (so an explicitly bulk-filled value, e.g. from an import, is preserved rather than overwritten).
• OriginalAuthor — sets original_author.field (default original_author_id) to the current user's id the same way, independently of Author. Meant as a permanent, foreign-key-free record of who created a row, for schemas where author_id has an ON DELETE SET NULL foreign key back to users.
• Owner — sets owner.field (default owner_id) to the current user's id, unless already set. Same behavior as Author, under its own field/config for models that need an owner distinct from an author.
• User — sets user.field (default user_id) to the current user's id, unless already set. Same behavior as Author, under its own field/config for models that need a user reference distinct from an author or owner.
• Client — sets client.field (default client_id) to the current user's client.reference attribute (default client_id), via getCurrentUserClientId().
• MachineName — sets machine_name.field (default machine_name) from machine_name.reference (default name), via ResolvesMachineName.
• MachineNameAsId — same as MachineName, but writes to the model's primary key instead of a separate field. Use one or the other, never both — they share the assignMachineNameOnModelCreation method name and will fatal on a trait collision if combined.
• Slug — sets slug.field (default slug) from slug.reference (default name) via Str::slug(), using slug.separator/slug.language/slug.dictionary.
• ResolvesMachineName — internal; composed by MachineName and MachineNameAsId, not meant to be used directly on a model. Provides resolveMachineName() and resolveMachineNameReference().

It is recommended to always alias the traits to prevent class name collisions. For instance, if your model already has its own User/Client/etc. class reference then adding the short name of the matching class is likely to create an issue. The User trait is a perfect and very common example of this issue.

Nearly every Laravel app has its own App\Models\User. Because the User::class is commonly in the same namespace as the other models, it may be common for a developer to reference the User model directly without an explicit use statement (e.g. a belongsTo(User::class)). If you were to add use ...\Boot\User without the alias, then the trait will override the shared namespace model and cause errors. If the model already has an explicit use statement (e.g. use App\Models\User;), it will throw a fatal error instead.

For that reason, we always recommend aliasing the Boot/* traits on import (use ...\Boot\User as BootUser;).

Select Dropdown/Radio Button Helpers

Both under Coyote6\LaravelBase\Traits\Models, and both expose the same method name getAsOptions() — use one or the other, never both together on the same model:

• GetAsOptions — static::getAsOptions(string $key = 'id', string $field = 'name', int $limit = 0, int $page = 1, ?Closure $modifyQuery = null), a $key => $field option list. Defaults to id => name ordered by name; pass 'abbr', 'code', or any other attribute to key by that instead, $limit/$page to paginate ($limit = 0 returns everything), and a $modifyQuery closure to filter, re-order, or scope the underlying query.
• GetAsOptionsAbbr — deprecated. A thin shim over GetAsOptions::getAsOptions('abbr') that emits an E_USER_DEPRECATED notice on every call. Compose GetAsOptions and call getAsOptions('abbr') instead.

Nothing is cached — every call queries the database, so the column selection, order, page, and data are always current. Assign the result to a variable if one request needs it more than once.

Query Helpers

• GetBySlug (Coyote6\LaravelBase\Traits\Models\GetBySlug) — static::getBySlug(string $slug), looks up a record by slug.field (default slug).

Database Helpers

Both under Coyote6\LaravelBase\Traits\Database:

• DropsIndexes — dropForeignIfExists(Blueprint $table, string $column, ?string $foreignKey = null) and dropIndexIfExists(Blueprint $table, string $column, ?string $foreignKey = null, bool $isForeign = false), for migrations that need to safely drop a foreign key/index that may or may not exist yet.
• ServiceProviderSeedsDb — seedDbOnCommand($dir), called from a service provider's boot() to also run every seeder found in $dir whenever db:seed runs.

File Helpers

• ReadsCsv (Coyote6\LaravelBase\Traits\Files\ReadsCsv) — getItemsFromCSV(string $pathToFile): array, reads a CSV file into an array of associative rows keyed by the header row.

Global Helper Functions

Defined in src/Helpers/Helpers.php, autoloaded globally (no namespace):

• getCurrentUserId(): int|string|null — the authenticated user's id, or null.
• getCurrentUserClientId(): int|string|null — the authenticated user's client.reference attribute (default client_id), or null.

Examples

Author, Client, MachineName, and Slug together

app/Models/Example.php

On create, this fills author_id and client_id from the current user, and generates machine_name/slug from name — all only when not already set. BootTraits is what actually wires assignAuthorOnModelCreation()/assignClientOnModelCreation()/assignMachineNameOnModelCreation()/assignSlugOnModelCreation() into Eloquent's creating event; it must be included alongside the others.

OriginalAuthor

Add alongside Author for a permanent, foreign-key-free record of the original author (useful when author_id has an ON DELETE SET NULL foreign key and could later be nulled out):

MachineNameAsId

When the machine name itself should be the primary key, use MachineNameAsId instead of MachineName:

Overriding config

config/coyote6-base.php (after php artisan vendor:publish --tag=coyote6-base-config):

Get As Options

app/Models/Example.php

app/Http/Controllers/ExampleController.php

Options Keyed Or Labelled By Another Field

getAsOptions(string $key = 'id', string $field = 'name', int $limit = 0, int $page = 1, ?Closure $modifyQuery = null). $key is the array key, $field the label, $limit/$page paginate, and $modifyQuery is a closure handed the query builder before it runs — filter (where, whereIn, whereHas, a scope), re-order, whatever. When you pass it, it owns the ordering (the default $field ascending is not applied), so a filter-only closure should add its own orderBy. Any column works — abbr for states or countries, a code, a slug, etc.:

Every parameter has a default, so use named arguments to set just the one (or few) you need without spelling out the earlier ones or remembering their order:

app/Models/Example.php

Deprecated: the GetAsOptionsAbbr trait still works — as a shim over getAsOptions('abbr') that raises an E_USER_DEPRECATED notice — but there is no longer a reason to use it. Swap use GetAsOptionsAbbr; for use GetAsOptions; and pass 'abbr' at the call site.

Get By Slug

app/Models/Example.php

app/Http/Controllers/ExampleController.php

DropsIndexes

database/migrations/2024_01_01_000000_example_migration.php

ServiceProviderSeedsDb

app/Providers/AppServiceProvider.php

Every seeder class found in that directory now also runs whenever php artisan db:seed runs.

ReadsCsv