Search by

sanjid29 / laravel-starter-core

sanjid29

Core infrastructure for Laravel starter kit — base controllers, traits, middleware, and CRUD scaffolding commands.

Package info

github.com/sanjid29/laravel-starter-core

pkg:composer/sanjid29/laravel-starter-core

Statistics

Installs: 30

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v2.0.2 2026-11-10 09:21 UTC

README

Core infrastructure package for the Laravel Starter Kit. Provides base controllers, traits, middleware, and the CRUD scaffolding engine used by all application modules.

What This Package Provides

Component Location Purpose
BaseController src/Http/Controllers/BaseController.php Abstract CRUD engine
BaseDataTableController src/Http/Controllers/BaseDataTableController.php Yajra DataTables base
BaseReportController src/Http/Controllers/BaseReportController.php HTML/PDF/Excel/CSV/Print export engine
BaseService src/Services/BaseService.php Optional service layer with lifecycle hooks
BaseFormRequest src/Http/Requests/BaseFormRequest.php Form request with recordId() / isUpdating()
BaseObserver src/Observers/BaseObserver.php Auto-sets audit fields on all model events
BasePolicy src/Policies/BasePolicy.php Policy base class
HasActivityLog src/Traits/HasActivityLog.php Spatie activity log integration
HasAuditFields src/Traits/HasAuditFields.php created_by, updated_by, deleted_by columns
HasUuid src/Traits/HasUuid.php Auto-generates UUID on model creation
HasTags src/Traits/HasTags.php Polymorphic many-to-many tags via associables table
HasAssociations src/Traits/HasAssociations.php Polymorphic many-to-many engine used by HasTags and custom association traits
FeatureEnabled src/Http/Middleware/FeatureEnabled.php Gate routes on features.{name} settings
HandleImpersonation src/Http/Middleware/HandleImpersonation.php User impersonation (auto-pushed to web group)
HasPermission src/Http/Middleware/HasPermission.php permission: middleware alias
HasRole src/Http/Middleware/HasRole.php role: middleware alias
MakeCrudModule src/Console/Commands/MakeCrudModule.php make:crud-module Artisan command
RemoveCrudModule src/Console/Commands/RemoveCrudModule.php remove:crud-module Artisan command
MakeService src/Console/Commands/MakeService.php make:service Artisan command

Requirements

This package is designed to sit inside a host Laravel app that meets the following expectations. Most are satisfied by the Laravel Starter Kit; if you install the package standalone, wire these up yourself:

Requirement Needed for Notes
PHP 8.4+, Laravel 12 or 13 Everything See composer.json. Tested against both on CI.
spatie/laravel-permission with a module column on the permissions table make:crud-module migrations Generated migrations tag each permission with ['module' => '{kebab}']. Add a nullable module column to the Spatie permissions table (a published-migration tweak), or the seeding firstOrCreate will fail.
A Superuser role (or your configured superuser_role) Gate / policy bypass Gate::before and BasePolicy::before grant this role everything.
The throttle:api rate limiter Route::crudModule(..., public: true) Ships in Laravel's default skeleton (bootstrap/app.php / RouteServiceProvider). Define it if you've removed it.
Bootstrap 5 + Bootstrap Icons front-end Generated views & DataTable action columns Action buttons emit btn/bi bi-* markup.
Host layout views layouts.form.index and layouts.form.recycle-bin BaseController index / recycle-bin fallbacks Used when a module doesn't supply its own {viewPrefix}.index / .recycle-bin.
created_by / updated_by / deleted_by + deleted_at columns HasAuditFields, SoftDeletes The generated migration already includes these — add them to any hand-written tables that use the traits.
A setting() helper (optional) feature: middleware When present it overrides config('starter-core.features.*'); otherwise the config fallback is used.

Installation

composer require sanjid29/laravel-starter-core

The StarterKitServiceProvider is auto-discovered — no manual registration needed.

Publish config

php artisan vendor:publish --tag=starter-core-config

This creates config/starter-core.php where you can set the superuser role name, tag model, and standalone feature flags.

Publish and run migrations

Required if you use the HasTags / HasAssociations traits:

php artisan vendor:publish --tag=starter-core-migrations
php artisan migrate

Publish stubs (optional)

To customise the CRUD scaffold templates:

php artisan vendor:publish --tag=starter-core-stubs

Once published to stubs/crud-module/, make:crud-module will use your local copies instead of the package defaults.

Configuration

After publishing, config/starter-core.php exposes:

return [
    'superuser_role' => 'Superuser',        // role name that bypasses all gates
    'tag_model'      => 'App\\Models\\Tag', // model used by HasTags trait
    'features'       => [                   // fallback when setting() helper is absent
        // 'notifications' => false,
        // 'registration'  => true,
    ],
];

The features array is only used when the host app does not provide a setting() helper. If a setting() helper exists (as in the Laravel Starter Kit), it takes precedence and features are controlled from the database.

Components

StarterKitServiceProvider

Registers everything on boot:

  • Middleware aliases: permission:, role:, feature:
  • HandleImpersonation pushed to the web middleware group
  • Route::crudModule() macro
  • Gate::before Superuser bypass
  • make:crud-module, remove:crud-module, and make:service Artisan commands

Route::crudModule() Macro

Route::crudModule(
    string $prefix,
    string $controller,
    ?string $dtController = null,
    ?\Closure $extras = null,
    bool $public = false
): void

Registers a full set of routes under $prefix. The whole group is guarded by permission:{prefix}.view, and write/destructive actions add the matching {prefix}.{action} permission on top:

Route Permission
GET / (index) {prefix}.view + {prefix}.view-grid
GET /datatable (DataTables JSON) {prefix}.view + {prefix}.view-grid
GET /create {prefix}.create
POST / (store) {prefix}.create
GET /{record} (show) {prefix}.view
GET /{record}/edit {prefix}.update
PUT /{record} (update) {prefix}.update
DELETE /{record} (destroy) {prefix}.delete
GET /select (Select2 / AJAX search) {prefix}.view
GET /json (clean REST feed) {prefix}.view + {prefix}.view-grid
GET /recycle-bin {prefix}.restore
GET /recycle-bin/datatable {prefix}.restore
POST /{record}/restore {prefix}.restore
DELETE /{record}/force-delete {prefix}.force-delete

GET /json is only registered when a $dtController is passed (it lives on the DataTable controller).

Extra static routes passed via $extras are registered before the /{record} wildcard.

Example:

Route::crudModule('posts', PostController::class, PostDataTableController::class, function () {
    Route::get('/report', PostReportController::class)
        ->name('report')
        ->middleware('permission:posts.report');
});

Public read endpoints — public: true

The flag exposes only the two read feeds — GET /select and GET /json — without permission checks, behind the throttle:api rate limiter. Every other action (create, store, update, destroy, recycle-bin, …) stays permission-guarded exactly as above — public never unlocks writes.

// posts.select + posts.json become public (throttle:api); everything else stays guarded
Route::crudModule('posts', PostController::class, PostDataTableController::class, public: true);

Only the attributes a module explicitly whitelists via selectFields() and jsonFields() are ever serialized — so a public feed exposes exactly what you list, nothing more. Keep those lists minimal on public modules. throttle:api assumes the host app defines that rate limiter (it ships in Laravel's default skeleton).

BaseController

All CRUD module controllers extend BaseController. Configure it with class properties:

protected string $model = Post::class;
protected string $routePrefix = 'posts';
protected string $viewPrefix = 'posts';
protected ?string $service = PostService::class; // optional

Override points (all optional):

// Return extra data to merge into the create/edit view
protected function createViewData(): array {}
protected function editViewData(Model $record): array {}

// Reshape or denormalize validated data before saving (no service wired)
protected function transformStoreData(array $data): array {}
protected function transformUpdateData(array $data, Model $record): array {}

// Post-save hooks — sync associations, dispatch jobs, etc. (no service wired)
protected function afterStore(Model $record, array $data): void {}
protected function afterUpdate(Model $record, array $data): void {}

// Pre/post delete hooks (also called on force-delete)
protected function beforeDestroy(Model $record): void {}
protected function afterDestroy(Model $record): void {} // auto-cleans file/media fields

When a $service is wired, transformStoreData/transformUpdateData and afterStore/afterUpdate are not called — the service owns those responsibilities via its own hooks.

File uploads — handled automatically when $request->hasFile(...). Integrates with Spatie MediaLibrary and Storage.

Select2 / AJAX search

GET /select powers Select2 / AJAX dropdowns. It returns Select2's native shape with multi-column search, infinite-scroll pagination and a field whitelist:

{
  "results": [ { "id": 1, "name": "Acme Ltd.", "text": "Acme Ltd." } ],
  "pagination": { "more": true }
}

Query parameters: q (search term), page, per_page (capped at $selectLimit). id and text are always added, so Select2 works with no front-end mapping.

Quick config (single-column label, the common case):

protected string $selectLabelColumn  = 'name'; // the returned field + Select2 `text`
protected string $selectSearchColumn = 'name'; // column searched by `q`
protected int    $selectLimit        = 20;     // max page size

Override points for more control:

// Columns searched (OR, LIKE) against `q`
protected function selectSearchColumns(): array { return ['name', 'email', 'code']; }

// Attribute whitelist returned per result — this is the security boundary.
// id + text are added automatically.
protected function selectFields(): array { return ['id', 'name', 'email']; }

// Build the Select2 label (`text`) — any computed string, not just a column
protected function selectLabel(Model $record): string
{
    return "{$record->code} — {$record->name}";
}

// Scope the base query (active only, tenant filtering, …)
protected function selectQuery(Builder $query): Builder
{
    return $query->where('is_active', true);
}
  • selectFields() = what data comes back (the whitelist).
  • selectLabel() = what the human sees in the option (text).

Defaults are derived from $selectLabelColumn / $selectSearchColumn, so setting those is enough for simple cases.

BaseDataTableController

Configure with class properties in the constructor:

protected string $model = Post::class;
protected string $routePrefix = 'posts';
protected array $withRelations = ['author', 'category'];
protected array $rawColumns = ['action', 'status'];

Override points:

protected function indexQuery(): Builder {}          // base query
protected function dataTableColumns(): array {}      // DataTables column definitions
protected function applyFilters(EloquentDataTable $dt, Request $request): EloquentDataTable {}
protected function actionColumn(mixed $record): string {} // action button HTML
protected function tableColumns(): array {}          // visible column list for the view

Clean REST JSON API

GET /json returns a clean, paginated feed decoupled from the DataTables envelope — no draw/recordsTotal, no HTML action columns. It reuses indexQuery(), so the public feed and the admin grid can never drift apart. Ideal for public pages or external API consumers.

{
  "data": [ { "id": 1, "name": "Acme" } ],
  "meta": { "current_page": 1, "per_page": 15, "total": 42, "last_page": 3 },
  "links": { "first": "…?page=1", "last": "…?page=3", "prev": null, "next": "…?page=2" }
}

Query parameters: q (search), sort + direction (asc/desc, whitelisted), page, per_page (capped at $jsonMaxPerPage, default $jsonDefaultPerPage).

Override points:

// Attribute whitelist returned per row — the security boundary. Defaults to the
// non-HTML columns from tableColumns(). Supports dot-paths for eager-loaded
// relations, e.g. 'category.name' (resolved via data_get()).
protected function jsonFields(): array { return ['id', 'name', 'category.name']; }

// Columns searched (OR, LIKE) by `q`. Relation dot-paths are excluded by default.
protected function jsonSearchColumns(): array { return ['name']; }

// Columns the client may sort by (?sort=&direction=)
protected function jsonSortableColumns(): array { return ['name', 'created_at']; }

// Custom serialization (casts, computed values, nested resources)
protected function jsonResource(mixed $record): array { return [...]; }

// Builder-level filters — status/date-range, or relation search via whereHas()
protected function applyApiFilters(Builder $query, Request $request): Builder { return $query; }

// Page-size tuning
protected int $jsonDefaultPerPage = 15;
protected int $jsonMaxPerPage     = 100;

Default search/sort exclude relation (dot-path) columns, since you can't orWhere/orderBy them directly — handle those in applyApiFilters() with whereHas(). On a module exposed with public: true, jsonFields() is your public surface; the generated stub pins it to ['id', 'name'] so you widen it deliberately.

BaseReportController

Handles multi-format export (HTML, PDF, Excel, CSV, Print) from a single controller action. Extend and implement:

protected function query(): Builder {}
protected function columns(): array {}              // column definitions with headings
protected string $title = 'Report Title';
protected string $filename = 'report';

BaseService

Optional service layer for modules that have business logic beyond simple CRUD. Only create one when needed — use php artisan make:service {Name} to scaffold it, then wire it into the controller:

// in the controller constructor
$this->service = app(PostService::class);

Hook execution order for create($data):

transformForCreate($data)  → reshape/denormalize data
beforeCreate($data)        → side-effects before insert
Model::create($data)
afterCreate($record, $data) → sync relations, dispatch jobs

Hook execution order for update($record, $data):

transformForUpdate($data, $record) → reshape/denormalize data
stripImmutable($data)              → remove protected fields
beforeUpdate($record, $data)       → side-effects before update
$record->update($data)
afterUpdate($record, $data)        → sync relations, dispatch jobs

Override points:

// Data shaping and denormalization — runs before before* hooks
protected function transformForCreate(array $data): array {}
protected function transformForUpdate(array $data, Model $record): array {}

// Side-effects — external calls, relation syncing, job dispatching
protected function beforeCreate(array &$data): void {}
protected function afterCreate(Model $record, array $data): void {}
protected function beforeUpdate(Model $record, array &$data): void {}
protected function afterUpdate(Model $record, array $data): void {}
protected function beforeDelete(Model $record): void {}
protected function afterDelete(Model $record): void {}

Declare $immutable to prevent specific fields from ever being updated:

protected array $immutable = ['email', 'username'];

BaseFormRequest

All Form Requests extend this. Key methods:

$this->recordId()    // returns the {record} route parameter (UUID/ID)
$this->isUpdating()  // true when the route has a {record} parameter

authorize() always returns true — authorization is handled by route middleware.

BaseObserver

Auto-sets created_by, updated_by, and deleted_by on every model event using the authenticated user's ID. All module observers extend this:

class PostObserver extends BaseObserver
{
    public function deleting(Post $post): void
    {
        parent::deleting($post); // sets deleted_by
        // cascade logic here
    }
}

Model Traits

Trait What it does
HasUuid Generates a uuid value on creating. The model keeps its auto-increment id as primary key — uuid is a secondary unique column
HasAuditFields Adds created_by, updated_by, deleted_by to $appends; provides createdBy(), updatedBy(), deletedBy() BelongsTo relations
HasActivityLog Configures Spatie Activity Log with logOnlyDirty() and dontSubmitEmptyLogs()
HasTags Tagify-compatible tag storage and retrieval via associables
HasAssociations Polymorphic many-to-many engine — one associables table for all relationships

HasAssociations — custom relationship traits

HasAssociations is the engine. You never use it directly on a model — instead you write a thin trait per related model that wraps associates(). This keeps one associables table serving all your polymorphic many-to-many relationships with no extra migrations.

// create once per related model:
trait HasSkills
{
    use HasAssociations;

    public function skills(): BelongsToMany
    {
        return $this->associates(Skill::class);
    }
}

// use on any model:
class Employee extends Model
{
    use HasSkills, HasTags; // both work independently via the same table
}

$employee->skills()->sync([1, 3, 5]);
$employee->tags;

When not to use this: if your pivot needs extra columns specific to the relationship (e.g. proficiency_level on employee_skill), a dedicated pivot table is cleaner.

Middleware

feature:name — Aborts with 404 if setting('features.name') is falsy.

permission:module.action — Checks Spatie permission; redirects with flash error on failure.

role:RoleName — Checks Spatie role; redirects with flash error on failure.

HandleImpersonation — Auto-pushed to web group. Reads session('impersonating') and swaps the auth user. Prevents impersonating Superusers without Superuser privilege.

CRUD Scaffold Commands

make:crud-module {Name}

Generates a complete module from stubs in stubs/crud-module/:

Generated file Destination
Migration database/migrations/
Model app/Models/
Observer app/Observers/
Policy app/Policies/
Form Request app/Http/Requests/
CRUD Controller app/Http/Controllers/CrudController/
DataTable Controller app/Http/Controllers/DataTableController/
Report Controller app/Http/Controllers/ReportController/
Views (index, form, show, report/index, report/print) resources/views/{kebab-name}/

Use --force to overwrite existing files.

After generating, the developer must:

  1. Run the migration
  2. Add $fillable and casts to the model
  3. Add validation rules to the Form Request
  4. Register routes with Route::crudModule() in routes/web.php
  5. Add sidebar links (both sidebar files)

remove:crud-module {Name} --force

Deletes all files generated by make:crud-module. Does not roll back the migration — run php artisan migrate:rollback manually if needed.

make:service {Name}

Generates a service class for a model at app/Services/{Name}Service.php. Only run this when the module has business logic that goes beyond simple CRUD — data transformation, denormalization, or orchestration across multiple models.

php artisan make:service LeaveRequest
# → app/Services/LeaveRequestService.php

Use --force to overwrite an existing file. The stub can be customized by publishing stubs and editing stubs/service.stub.

Stubs

Stubs live in stubs/ and can be published to the host application for customization:

php artisan vendor:publish --tag=starter-core-stubs
Stub Used by
stubs/crud-module/*.stub make:crud-module
stubs/service.stub make:service

Once published, the commands will use your local copies in stubs/ instead of the package defaults.

License

MIT