Laravel Helpers Laravel Package

Getting Started

• Install with composer require ronasit/laravel-helpers. The package is Laravel-auto-discovered; no manual provider registration is normally required. If you keep a config/app.php providers list, check composer.json → extra.laravel.providers for the exact provider name.
• First place to look is the package src/ tree, especially Traits/, Exceptions/, and any Commands/ directory. The README covers the high-level feature list, but the traits are where most day-to-day value lives.
• First practical use case: add the response/JSON helper traits to your base controller and standardise API responses, then centralise domain exception rendering in bootstrap/app.php (Laravel 11+) or app/Exceptions/Handler.php (Laravel 10 and below).
• If you are adopting 3.8.3: search your codebase for imports of exception classes from RonasIT\Support\Exceptions\* that relate to entity generation/handling. They are now deprecated in favour of the EntityGenerator package. Existing catches still work in 3.8.x, but plan the import move before the next major.
• Run composer show ronasit/laravel-helpers and php artisan about after install to confirm the version and that no provider/config conflicts were introduced.

Implementation Patterns

Response standardisation

Use the package response traits in an abstract ApiController so every controller inherits the same envelope:

abstract class ApiController extends Controller
{
    use JsonResponseTrait; // or the response trait exposed by your installed version
}

This keeps status codes, payload wrapping, and error shapes consistent without repeating response()->json(...) in every action.

Exception → HTTP mapping

Register renderers once, rather than catching in controllers:

// bootstrap/app.php (Laravel 11+)
->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (ResourceNotFoundException $e) {
        return response()->json(['message' => $e->getMessage()], 404);
    });
})

For Laravel 10, the equivalent belongs in app/Exceptions/Handler.php::register(). This is the main integration point for the package's exception classes.

Model search / filtering traits

Apply the package model traits to Eloquent models to get query-string-driven search, ordering, and pagination:

class Order extends Model
{
    use ModelTrait;
}

Treat these traits as a starting point rather than a security boundary — validate or whitelist searchable/sortable columns at the controller or form-request layer, because the traits commonly read directly from the request.

Entity/CRUD services

Where the package provides service, repository, or entity-control traits, the common workflow is: thin controller → service method → repository/model trait. Keep business rules in the service, and let the package handle repetitive lookup/CRUD plumbing. If you are also using RonasIT/laravel-entity-generator, prefer the generator's classes and exceptions as the primary source and use laravel-helpers for the generic HTTP/response plumbing.

Deprecation migration pattern (3.8.3)

For any deprecated exception currently imported from this package, either:

1. Update the use statement to the EntityGenerator namespace and add laravel-entity-generator as a direct dependency, or
2. Add a thin app-level exception that extends the new class and catch that, insulating your handlers from future namespace moves.

Do not rely on catching the deprecated class by FQCN if you expect the package to drop it in a major release.

Testing

Assert against the standardised envelope rather than raw JSON, e.g. assertJsonStructure, assertStatus, and assertJsonPath('message', ...). If your tests catch specific exception classes, they will need the same import update as production code.

Gotchas and Tips

• Deprecations are notices, not errors — until they are. 3.8.3 only marks the exception classes deprecated. Runtime behaviour is unchanged, but deprecation notices can pollute logs or fail strict CI setups (convertDeprecationsToExceptions, PHPUnit deprecation reporting, PHPStan baseline). Suppress or fix the imports rather than ignoring them.
• Trait method collisions. These traits are broad. If your base controller or model already defines response, search, index, or similar, PHP will fatal on the collision. Alias with use TraitA { method as traitMethod; } or refactor the conflicting method.
• Implicit request coupling. Model-level search traits typically read from the current request, which makes unit tests awkward. In tests, set query parameters via $this->get('/endpoint?search=...') or bind a request instance; avoid calling trait methods directly without a request context.
• Config caching. If you publish package config, remember php artisan config:clear after edits. Stale cached config is the usual cause of "it worked locally" surprises.
• Exception handler placement matters. Laravel 11 moved exception configuration into bootstrap/app.php. Copying examples written for Laravel 10's Handler.php into an 11+ app silently does nothing.
• Catch the parent, not the alias. If you need to support both the deprecated and new exception namespaces during a transition, catch a shared base class or interface where available, rather than duplicating catch blocks.
• Version pinning. If you depend on the deprecated exceptions, pin ^3.8 and treat the eventual removal as a breaking upgrade. Check the changelog for the major release that drops them before upgrading.
• Extension points. Prefer extending the package traits/services in your own app/Support namespace over editing vendor code; publishable config and container bindings are the intended override mechanisms where offered.
• Debugging. When a helper behaves unexpectedly, read the actual trait in vendor/ronasit/laravel-helpers/src/ — the README often lags behind the code, and the 3.8.x line has been refactoring classes out to companion packages.