Download the PHP package damianulan/laravel-lucent without Composer

Laravel Lucent

Laravel Lucent is a utility package for Laravel applications that bundles a small set of reusable primitives:

• Transaction-oriented service classes
• Composer class discovery via Magellan scopes
• Eloquent traits for UUIDs, access scopes, cascade deletes, pruning, and model state helpers
• HTML sanitizing and trait inspection helpers
• String and currency lookup utilities
• A few console generators and maintenance commands

The package is intentionally lightweight. Most features are opt-in and can be used independently.

Requirements

• PHP ^8.3
• illuminate/support ^9.0|^10.0|^11.0|^12.0
• mews/purifier ^3.4

Installation

Install the package with Composer:

Laravel package discovery registers the service provider automatically.

If you want the package config, translations, and stubs in your application, publish them:

You can also publish individual groups:

What The Package Includes

Services

Lucent\Services\Service is a base class for application services that:

• accepts named boot parameters
• runs handle() inside a database transaction
• supports optional authorization and validation
• collects runtime or validation errors
• exposes the original input and the returned result
• provides a small cache helper via remember()

Generate a service class:

Example service:

Execute it from a controller or action:

Useful methods:

• boot(...$props): instantiate the service with named arguments
• execute(): run authorization, then handle() inside DB::transaction()
• add(...$props): append more named data after booting
• request(): access the bound request or an empty request object
• getOriginal(): get the original booted input as a collection
• getResult(): get the value returned by handle()
• getErrors(): get collected validation/runtime messages
• hasErrors(): check whether any errors were collected
• toArray() / toJson(): serialize the original input payload

Notes:

• execute() only marks the service as passed when handle() returns a truthy value.
• If authorization fails or an exception is thrown, the exception is reported and the message is added to the error bag.

Magellan Scopes

Lucent\Support\Magellan\MagellanScope lets you discover classes from Composer's class map and filter them with reflection-based rules.

This is useful when you want to locate application classes or approved vendor classes dynamically, for example form builders, policies, handlers, or plugin-like classes.

Generate a scope:

Inline usage:

Custom scope class:

Then use it:

Important behavior:

• The scope reads from vendor/composer/autoload_classmap.php
• Application classes are included by default
• Vendor classes are excluded by default unless allowed in config/lucent.php under magellan.vendor_include
• Implement ScopeUsesCache to cache the collected class list

Helpers available on a filled scope:

• get()
• fill()
• toArray()
• toJson()
• count()

Eloquent Traits

Accessible

Adds a local scope named checkAccess() which applies a custom Eloquent scope stored on the model.

The configured scope class must extend Illuminate\Database\Eloquent\Scope.

UUID

Adds UUID primary key support.

Migration example:

The trait disables incrementing and fills the primary key with Str::uuid() on create.

HasUniqueUuid

Adds a unique UUID column without replacing the model primary key.

Migration example:

Lookup methods:

If your UUID column has a different name, override:

VirginModel

Adds convenience helpers around common boolean active and draft flags.

Available helpers:

active() and drafted() scopes only apply when the corresponding fields are present in $fillable.

CascadeDeletes

Deletes related models when the parent model is deleted. This works through the deleted model event, so it does not run for mass deletes that bypass model events.

If cascadeDelete is omitted and lucent.models.auto_cascade_deletes is enabled, Lucent tries to detect deletable relation methods automatically based on the configured relation return types.

You can also block specific relations:

Configuration:

SoftDeletesPrunable

Provides a prunableSoftDeletes() scope for models using Laravel's SoftDeletes.

This scope is used by the pruning command described below.

Helpers

clean_html()

Sanitizes rich HTML input using the package's dedicated Purifier preset.

Examples:

Lucent merges an extra lucent_config entry into purifier.settings at boot time. The defaults are defined in config/lucent.php and allow common rich-text tags, safe links, some formatting classes, and selected inline CSS properties.

class_uses_trait()

Checks whether a class uses a trait anywhere in its inheritance tree.

Signature:

Support Utilities

Lucent\Support\Str\Alphabet

Utility for working with Latin letters, including accented UTF-8 variants.

The class normalizes accented characters to their ASCII base where possible before calculating the alphabet position.

Lucent\Support\Str\Currencies\CurrencyLib

Provides an in-memory ISO 4217 currency dataset.

Returned items use this shape:

Methods:

• getByCode(string $code)
• getByAlpha3(string $alpha3)
• getByNumeric(string $numeric)
• getAll()

getByAlpha3() and getByNumeric() validate input format before lookup and throw an exception on invalid values.

Lucent\Console\Git

Structured helper around common git queries and release-oriented commands:

For richer inspection, build a repository-scoped instance:

It also exposes:

• checkoutRelease(string $tag)
• checkoutLatestRelease()

Each executed command is captured as a GitResult object with the command, working directory, exit code, output, error output, and inferred caller metadata.

Lucent\Support\Trace

Captures and inspects the current backtrace:

Useful helpers:

You can also build a trace from an exception:

Reflection is used internally to enrich frames with method signatures, namespaces, and callable metadata, making the tool suitable for debugging chained service calls, controller pipelines, and vendor-to-app handoffs.

Artisan Commands

make:service

Creates a service class in App\Services.

make:magellan

Creates a Magellan scope in App\Support\Magellan.

model:prune-soft-deletes

Permanently deletes soft-deleted records for models that:

• live under App\Models
• extend Illuminate\Database\Eloquent\Model
• use Laravel's SoftDeletes trait
• use Lucent\Support\Traits\SoftDeletesPrunable

Run it manually:

Schedule it:

Configure the age threshold in config/lucent.php or through environment:

Configuration

Published config file: config/lucent.php

Main options:

Use magellan.vendor_include when a scope should inspect specific vendor namespaces from the Composer class map.

Typical Use Cases

• Wrap multi-step create/update flows in a dedicated service class
• Apply model-specific access constraints through reusable Eloquent scopes
• Add UUID primary keys or public UUID identifiers to Eloquent models
• Automatically cascade deletes through selected relations
• Sanitize rich text input before persisting or rendering it
• Discover application classes dynamically using reflection and Composer metadata
• Prune stale soft-deleted records on a schedule

Caveats

• Services are considered successful only when handle() returns a truthy value.
• Cascade delete logic relies on model events and will not run for mass delete queries that skip events.
• Magellan depends on Composer's generated class map. If class discovery looks stale, refresh autoload metadata with composer dump-autoload.
• The Lucent pipeline layer is deprecated.

License

MIT. See LICENSE.

Contact

Questions and contributions: [email protected]