Getting Started

Minimal Setup

Install the package:

composer require laracraft-tech/laravel-useful-additions

Publish the config (optional, for customization):

php artisan vendor:publish --tag="useful-additions-config"

First Use Case: Enums

For PHP 8.1+ projects, leverage UsefulEnums to simplify enum handling:

use LaracraftTech\LaravelUsefulAdditions\Traits\UsefulEnums;

enum Status: string {
    use UsefulEnums;
    case Active = 'active';
    case Inactive = 'inactive';
}

// Usage:
Status::names();   // ['Active', 'Inactive']
Status::values();  // ['active', 'inactive']
Status::array();   // ['Active' => 'active', 'Inactive' => 'inactive']

First Use Case: Scopes

Apply UsefulScopes to Eloquent models for reusable query patterns:

use LaracraftTech\LaravelUsefulAdditions\Traits\UsefulScopes;

class Post extends Model {
    use UsefulScopes;
}

// Exclude columns dynamically:
Post::selectAllBut(['deleted_at'])->get();

// Filter by date ranges:
Post::fromToday()->get(); // Created today
Post::fromYesterday()->get(); // Created yesterday

First Use Case: Database Truncation

Reset your database quickly during development:

# Truncate all tables
php artisan db:truncate

# Truncate specific tables (e.g., 'users', 'posts')
php artisan db:truncate --tables=users,posts

# Disable foreign key checks (safer for complex schemas)
php artisan db:truncate --no-foreign

Implementation Patterns

1. Enums in Practice

Migrations: Use Status::values() to define enum columns:

Schema::create('posts', function (Blueprint $table) {
    $table->string('status')->default(Status::Active->value);
});

Validation: Convert enums to arrays for validation rules:
```
$validator->rule('status', Rule::in(Status::array()));
```

API Responses: Map enums to human-readable labels:

$statusLabels = collect(Status::array())->flip();

2. Scopes for Eloquent

Dynamic Column Selection: Use selectAllBut() to exclude sensitive columns (e.g., password, api_token) in API responses:
```
User::selectAllBut(['password', 'api_token'])->get();
```
Date-Based Filtering: Combine scopes with other query methods:
```
Post::fromToday()->where('author_id', 1)->get();
```

Custom Scopes: Extend UsefulScopes to add project-specific scopes:

trait CustomScopes {
    public function scopePublished($query) {
        return $query->where('published_at', '<=', now());
    }
}

3. Database Management

Local Development: Use db:truncate to reset the database between feature branches:
```
php artisan db:truncate --force
```
CI/CD Pipelines: Integrate db:truncate into deployment scripts to ensure a clean state:
```
php artisan db:truncate --tables=migrations,users --no-interaction
```
Testing: Replace RefreshDatabaseFast (deprecated) with Laravel’s built-in RefreshDatabase or use db:truncate for faster test resets:
```
// In Pest/PHPUnit tests:
uses(RefreshDatabase::class);
```

4. Workflow Integration

API Controllers: Use selectAllBut() to sanitize model outputs:

public function index() {
    return User::selectAllBut(['password', 'remember_token'])->get();
}

Admin Panels: Leverage fromToday/fromYesterday for activity dashboards:

$todayLogs = Log::fromToday()->get();
$yesterdayLogs = Log::fromYesterday()->get();

Seeding: Generate seed data using Status::array() for consistency:

factory(Post::class)->createMany([
    'status' => array_rand(Status::array(), 10)
]);

Gotchas and Tips

1. UsefulEnums

PHP Version Requirement: Requires PHP 8.1+. Ensure your project meets this requirement before using UsefulEnums.
Backward Compatibility: For PHP < 8.1, manually implement enum-to-array logic or use a polyfill.

Performance: Status::array() creates a new array on each call. Cache the result if used frequently:

private static ?array $statusArray = null;
public static function array(): array {
    return self::$statusArray ??= array_combine(self::names(), self::values());
}

2. UsefulScopes

Column Caching: selectAllBut() caches table columns. Clear the cache after migrations:

php artisan cache:clear

Or manually trigger a refresh:

\LaracraftTech\LaravelUsefulAdditions\Traits\UsefulScopes::clearColumnCache('posts');

MySQL Limitations: selectAllBut() uses dynamic SQL. Avoid using it with computed columns or JSON columns in MySQL < 8.0.
Timestamp Requirement: fromToday/fromYesterday require created_at timestamps. Add a default if missing:
```
$table->timestamp('created_at')->useCurrent();
```

3. db:truncate Command

Foreign Key Constraints: Disable checks for complex schemas:
```
php artisan db:truncate --no-foreign
```
Transaction Safety: The command runs in a transaction by default. For large databases, disable it with --no-transaction:
```
php artisan db:truncate --no-transaction
```
Excluded Tables: Skip system tables (e.g., migrations) if needed:
```
php artisan db:truncate --ignore=migrations
```
Performance: Truncating tables is faster than dropping/recreating them. Use this for local/dev environments.

4. Debugging and Edge Cases

Column Cache Issues: If selectAllBut() returns unexpected columns, verify the cache is updated:
```
php artisan cache:clear
```
Enum Key Conflicts: Ensure enum values are unique. Duplicate values will cause Status::array() to overwrite keys.
Timezone Handling: fromToday/fromYesterday respect the app’s timezone. Set it explicitly in config/app.php:
```
'timezone' => 'UTC',
```
Deprecated Trait: RefreshDatabaseFast is deprecated. Use Laravel’s RefreshDatabase instead:
```
use Illuminate\Foundation\Testing\RefreshDatabase;
```

5. Extension Points

Custom Scopes: Extend UsefulScopes to add project-specific methods:

trait AppScopes {
    public function scopeActive($query) {
        return $query->where('status', Status::Active->value);
    }
}

Enum Helpers: Add static methods to enums for project-specific logic:

enum Role {
    use UsefulEnums;
    case Admin;
    case User;

    public static function isAdmin($value) {
        return $value === self::Admin->value;
    }
}

Command Customization: Override the db:truncate command logic by publishing and modifying the config:
```
php artisan vendor:publish --tag="useful-additions-config"
```
Then extend the TruncateTables command in app/Console/Commands/TruncateTables.php.

6. Testing Tips

Pest/PHPUnit: Use db:truncate in test setups for faster resets:

beforeEach(function () {
    \Artisan::call('db:truncate');
});

Database States: Combine with RefreshDatabase for hybrid approaches:

uses(RefreshDatabase::class)->beforeEach(function () {
    \Artisan::call('db:truncate', ['--ignore' => 'migrations']);
});

Laravel Useful Traits Laravel Package