Getting Started

Minimal Steps to Begin

Installation:
```
composer require tastyigniter/core
```
Ensure your composer.json specifies PHP 8.3–8.4 compatibility.
Publish Core Configurations:
```
php artisan vendor:publish --provider="TastyIgniter\Core\Providers\CoreServiceProvider"
```
This publishes:
- Admin panel configurations (config/admin.php)
- Media storage settings (config/media.php)
- Dashboard widgets (config/dashboard.php)

First Use Case: Admin Panel Integration Register a custom admin route in routes/admin.php:

Route::resource('custom-module', \TastyIgniter\Core\Http\Controllers\Admin\CustomModuleController::class);

Extend the base AdminController for CRUD operations:

use TastyIgniter\Core\Http\Controllers\Admin\AdminController;

class CustomModuleController extends AdminController
{
    protected $model = \App\Models\CustomModule::class;
    protected $view = 'admin.custom-modules.index';
}

Verify Extensions Check installed extensions via:
```
php artisan igniter:extensions
```
Update dependencies with:
```
php artisan igniter:update
```

Where to Look First

Documentation: TastyIgniter Docs (covers admin panel, extensions, and core APIs).
Core Classes:
- TastyIgniter\Core\Foundation\Application (bootstrapping)
- TastyIgniter\Core\Http\Controllers\Admin\AdminController (base admin controller — now also owns the suppressNavigation layout flag)
- TastyIgniter\Core\Services\TemplateSandbox (sanitization logic, incl. SVG handling)
Config Files: config/admin.php, config/media.php (critical for customization).

Artisan Commands:

php artisan list | grep igniter  # Lists core commands

First Practical Task

Create a Custom Admin Module:

Generate a model and migration:
```
php artisan make:model CustomModule -m
```
Extend AdminController (as shown above) and define views in resources/views/admin/custom-modules/.
Register the route and test via /admin/custom-module.

If the module is a full-screen editor/wizard, opt out of the chrome on day one (v4.4.5+):

class CustomModuleController extends AdminController
{
    protected $suppressNavigation = true;
}

Implementation Patterns

Core Workflows

1. Admin Panel Development

Pattern: Extend AdminController for CRUD.

class PostsController extends AdminController
{
    protected $model = \App\Models\Post::class;
    protected $view = 'admin.posts.index';
    protected $columns = ['title', 'published_at']; // Customize columns
}

Key Methods:
- index(): Lists records (uses $columns).
- create()/edit(): Renders forms (uses makeForm()).
- store()/update(): Handles validation (uses validate()).

Form Handling: Use makeForm() to define fields:

protected function makeForm()
{
    return [
        'title' => 'text',
        'content' => 'textarea',
        'published_at' => 'datetime',
    ];
}

2. Chrome-less Admin Screens (`suppressNavigation`, new in v4.4.5)

Pattern: Set the flag per controller to hide the header + sidebar in the default admin layout.

class OnboardingWizardController extends AdminController
{
    protected $suppressNavigation = true;
}

When to use it:
- Full-screen editors, media managers, POS/checkout style flows.
- First-run onboarding wizards that should not let the user wander off.
- Print/Kiosk views that render inside an admin route.
When not to use it: Any resource screen where the operator still needs the sidebar to jump between modules — you must re-provide a way back (a "Back to dashboard" link or redirect after save), since the nav is gone.
Note: It is a layout concern only; middleware, breadcrumbs and route guards still apply. It does not create a separate layout file.

3. Extension System

Pattern: Create a custom extension (e.g., for payments).

Structure:

/extensions/PaymentGateway/
  ├── config/
  ├── resources/
  ├── src/
  │   ├── Http/Controllers/
  │   ├── Providers/
  │   └── Services/
  └── composer.json

'payment-gateway' => [
    'path' => base_path('extensions/PaymentGateway'),
    'enabled' => true,
],

Publish assets:

php artisan vendor:publish --tag=payment-gateway-assets

Key Classes:
- ExtensionServiceProvider: Bootstraps extension logic.
- ExtensionController: Handles routes (e.g., /admin/payment-gateway).

4. Template Sanitization

Pattern: Use TemplateSandbox for user-generated templates.

use TastyIgniter\Core\Services\TemplateSandbox;

$sandbox = new TemplateSandbox();
$sanitized = $sandbox->sanitize($userInputTemplate);

Common Use Cases:
- Email templates (e.g., resources/views/emails/custom.blade.php).
- Admin theme customizer (e.g., dynamic dashboard widgets).

Custom Rules: Extend TemplateSandbox:

class CustomSandbox extends TemplateSandbox
{
    protected function getAllowedTags()
    {
        return parent::getAllowedTags() + ['custom-tag'];
    }
}

5. Media Management

Pattern: Attach media to models.

use TastyIgniter\Core\Traits\HasMedia;

class Post extends Model
{
    use HasMedia;
}

Usage:

$post = new Post();
$post->addMediaFromPath($path)->toMediaCollection('images');
$post->save();

Config: Adjust config/media.php for storage (e.g., S3, local). SVG uploads are sanitized through enshrined/svg-sanitize, now on ^1.0.

6. Dashboard Widgets

Pattern: Register custom widgets.

Define in config/dashboard.php:

'widgets' => [
    'custom' => [
        'class' => \App\Widgets\CustomWidget::class,
        'priority' => 10,
    ],
],

Implement WidgetInterface:

class CustomWidget implements WidgetInterface
{
    public function render()
    {
        return view('widgets.custom');
    }
}

Integration Tips

Laravel Ecosystem

Authentication: Use Laravel’s auth() helper or extend TastyIgniter\Core\Auth\AuthManager.
Events: Dispatch core events (e.g., extension.installed):
```
event(new ExtensionInstalled($extension));
```
Queue Jobs: Leverage Laravel’s queue system for async tasks (e.g., media processing).

Performance

Database: Add indexes to media_attachments, languages, etc., as shown in v4.2.0.

Caching: Use CacheMaker trait:

use TastyIgniter\Core\Traits\CacheMaker;

class MyService
{
    use CacheMaker;

    public function getCachedData($key)
    {
        return $this->cache->remember($key, now()->addHours(1), function () {
            return $this->fetchData();
        });
    }
}

Localization

Languages: Manage via TastyIgniter\Core\Models\Language.

Translations: Use Laravel’s trans() or extend the Language model:

$language = Language::find(2);
$translation = $language->translations()->where('key', 'welcome')->first();

Debugging

Log Viewer: Access via /admin/logs (admin panel).

Flash Messages: Use FlashBag:

flash()->success('Action completed!')->withActionUrl('/admin/posts');

Gotchas and Tips

Pitfalls

1. Upgrading to v4.4.5: SVG Sanitizer Major Bump

Issue: enshrined/svg-sanitize moved from ^0.22 to ^1.0 — a major version jump. Anything that pinned ^0.22, subclasses the sanitizer, or calls its API directly can break.
- Fix: Run composer update enshrined/svg-sanitize in your app and in every extension that declares the constraint, then re-test SVG upload/preview paths:
```
composer update enshrined/svg-sanitize --with-dependencies
php artisan media:optimize   # re-run thumbnails if previews look wrong
```
- Check: composer why enshrined/svg-sanitize to find which extension is holding back the old constraint.
- Note: composer.json constraint conflicts are the most likely upgrade failure; a composer update that "does nothing" usually means an extension still requires ^0.22.

2. Template Sanitization Quirks

Issue: TemplateSandbox may strip custom Blade directives.
- Fix: Whitelist directives in getAllowedDirectives():
```
protected function getAllowedDirectives()
{
    return ['customDirective'];
}
```
Issue: Nested components may break sanitization.
- Fix: Use @verbatim for complex components:
```
@verbatim
    {{!! $unsafeComponent !!}}
@endverbatim
```

3. `suppressNavigation` Behavioural Gotchas

Issue: Setting the flag at the base controller level removes navigation from every action, including create/edit follow-up screens where users need to get back.
- Fix: Set it on the specific controller/action, or toggle it:
```
public function index() { $this->suppressNavigation = true; return parent::index(); }
```
Issue: Extensions overriding the layout may not honour the flag — the option affects the default admin layout only.
- Fix: If you ship a custom admin layout, read and respect $this->suppressNavigation yourself.
Issue: Users "stuck" on a full-screen page with no nav.
- Fix: Always render an explicit exit link/redirect target in the view.

4. Extension Loading

Issue: Extensions fail to load if composer.json is missing.
- Fix: Ensure extensions have a valid extra.igniter config:
```
{
  "extra": {
    "igniter": {
      "type": "extension",
      "name": "payment-gateway"
    }
  }
}
```
Issue: Circular dependencies between extensions.
- Fix: Use igniter:update --check to validate dependencies.

5. Media Handling

Issue: Media not appearing in the admin panel.
- Fix: Verify config/media.php paths and run:
```
php artisan storage:link
```
Issue: Large media files slow down the admin panel.
- Fix: Use media:optimize to regenerate thumbnails:
```
php artisan media:optimize
```

6. Admin Panel Routes

Issue: Custom routes conflict with core routes.
- Fix: Prefix routes:
```
Route::prefix('custom-modules')->group(function () {
    Route::resource('/', CustomModuleController::class);
});
```
- Always re-run php artisan route:list | grep admin after adding routes, and clear caches (route:clear, view:clear) when a new controller 404s instead of rendering.

7. Console Command Confirmations (fixed in v4.4.5)

Issue: Prior versions could mis-handle interactive confirmation prompts (e.g. --no-interaction or piped input) in igniter: commands.
- Fix: Upgrade, and where you wrap Artisan commands in CI, explicitly pass --no-interaction rather than relying on the default prompt behaviour.

Core Laravel Package