Getting Started

Minimal Setup

Installation:
```
composer require lastdragon-ru/lara-asp-core
```
Ensure your composer.json meets the package's PHP (^8.1) and Laravel (^9.0) requirements.
Publish Config (if applicable): Run:
```
php artisan vendor:publish --provider="LastDragon\AspCore\AspCoreServiceProvider"
```
Check config/asp-core.php for package-specific configurations (if any).
First Use Case:
- Helper Functions: Check the src/Helpers directory for utility functions (e.g., string manipulation, array helpers).
- Base Classes: Extend LastDragon\AspCore\Base\BaseModel or LastDragon\AspCore\Base\BaseController for boilerplate reduction.
- Artisan Commands: Run php artisan to discover new commands (e.g., asp:generate:model).
Documentation:
- Browse the docs/ folder in the repository (if available) or inspect the src/ directory for class-level PHPDoc comments.

Implementation Patterns

1. Base Classes for Boilerplate Reduction

Model Layer: Extend BaseModel to inherit common traits like:
```
use LastDragon\AspCore\Base\BaseModel;

class User extends BaseModel
{
    // Inherits soft deletes, timestamps, and custom scopes
}
```
- Custom Scopes: Override scopeCustom() in BaseModel to add default query scopes.
- Accessors/Mutators: Use getAttribute() or setAttribute() overrides for consistent formatting (e.g., slugs, hashes).

Controller Layer: Extend BaseController for DRY API/JSON responses:

use LastDragon\AspCore\Base\BaseController;

class UserController extends BaseController
{
    public function index()
    {
        return $this->respondWithData(User::all());
    }
}

Response Helpers: Leverage respondWithData(), respondWithError(), or respondWithSuccess() for standardized JSON responses.

2. Utility Functions

String Helpers: Use LastDragon\AspCore\Helpers\Str:: for custom string operations (e.g., Str::toKebabCase()).
```
$kebab = Str::toKebabCase('HelloWorld'); // "hello-world"
```
Array Helpers: Utilize LastDragon\AspCore\Helpers\Arr:: for nested array manipulations (e.g., Arr::dot()).
```
$dotted = Arr::dot(['user' => ['name' => 'John']]); // "user.name" => "John"
```

Collection Macros: Extend Laravel Collections with custom macros in AppServiceProvider:

use LastDragon\AspCore\Helpers\CollectionMacros;

public function boot()
{
    CollectionMacros::register();
}

3. Artisan Commands

Generate Boilerplate: Use asp:generate:model to scaffold models/controllers with predefined logic:
```
php artisan asp:generate:model Post -a --api
```
- Flags like --api, --migration, or --seeder customize generation.

Custom Commands: Extend LastDragon\AspCore\Console\BaseCommand for project-specific tasks:

use LastDragon\AspCore\Console\BaseCommand;

class OptimizeCommand extends BaseCommand
{
    protected $signature = 'asp:optimize';
    protected $description = 'Optimize database tables';
}

4. Service Providers

Extend Functionality: Bind custom interfaces or extend existing bindings in AspCoreServiceProvider:

$this->app->bind(
    \LastDragon\AspCore\Contracts\Logger::class,
    \App\Services\CustomLogger::class
);

5. Testing

Mock Base Classes: Use BaseModel and BaseController in tests for consistent mocking:

$model = $this->partialMock(BaseModel::class, ['fillable']);
$model->expects($this->any())->method('fillable')->willReturn(['name']);

Gotchas and Tips

Pitfalls

Version Skew:
- The package supports Laravel 8–13 but may have undocumented breaking changes between minor versions. Pin to a specific version in composer.json:
```
"lastdragon-ru/lara-asp-core": "1.2.0"
```
Namespace Collisions:
- The package uses LastDragon\AspCore\ namespace. Ensure your project doesn’t shadow this (e.g., avoid App\AspCore).
- Fix: Use fully qualified aliases:
```
use LastDragon\AspCore\Helpers\Str as AspStr;
```
Undocumented Features:
- Some helpers (e.g., Arr::, Str::) may lack PHPDoc. Inspect the src/Helpers directory for usage examples.
BaseModel Pitfalls:
- Overriding fillable in child models may conflict with BaseModel's defaults. Explicitly merge:
```
protected $fillable = array_merge(
    parent::fillable,
    ['custom_field']
);
```
Artisan Command Conflicts:
- Custom commands might clash with Laravel’s built-in ones. Prefix with asp::
```
php artisan asp:custom-task
```

Debugging Tips

Enable Debug Mode: Set APP_DEBUG=true in .env to surface helper/function errors.

Log Helper Calls: Add debug logs in AppServiceProvider:

\Log::debug('Helper called:', ['function' => __FUNCTION__, 'args' => func_get_args()]);

Check for Deprecated Methods: Use php artisan ide-helper:generate to inspect method signatures.

Extension Points

Custom Helpers: Extend existing helpers by publishing and overriding them:
```
php artisan vendor:publish --tag=asp-core-helpers
```
Modify config/asp-core.php to point to your custom helper paths.

BaseModel Traits: Override traits in BaseModel (e.g., HasSoftDeletes) for project-specific logic:

use LastDragon\AspCore\Traits\CustomSoftDeletes;

class User extends BaseModel
{
    use CustomSoftDeletes;
}

Middleware Integration: Use BaseController middleware groups (e.g., auth:api) as a template:

protected $middlewareGroups = [
    'api' => [
        \App\Http\Middleware\CheckForMaintenance::class,
        \LastDragon\AspCore\Http\Middleware\ValidateSignature::class,
    ],
];

Event Listeners: Bind custom listeners to BaseModel events (e.g., saved, deleted) in AspCoreServiceProvider:

\Event::listen('eloquent.saved: App\Models\User', function ($model) {
    \Log::info("User saved: {$model->id}");
});

Performance Tips

Lazy-Load Helpers: Autoload helpers via composer.json:

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "LastDragon\\AspCore\\Helpers\\": "vendor/lastdragon-ru/lara-asp-core/src/Helpers/"
    }
}

Cache Helper Results: For expensive helper operations, cache results:

$result = Cache::remember("helper_{$input}", 60, function () use ($input) {
    return Str::complexOperation($input);
});

Avoid Overriding Core Methods: Prefer composition over inheritance for BaseModel/BaseController to minimize performance overhead.

Lara Asp Core Laravel Package