Getting Started

Minimal Steps to First Use

Installation
```
composer require baks-dev/core
```
Configure Domain Add your domain to .env:
```
HOST=yourdomain.example
```
Set Up Systemd Worker (Linux only) Copy the example service file from vendor/baks-dev/core/Resources/systemd to /etc/systemd/system/ (e.g., yourdomain.example-core-messenger@.service). Enable and start the service:
```
sudo systemctl daemon-reload
sudo systemctl enable yourdomain.example-core-messenger@yourdomain.example.service
sudo systemctl start yourdomain.example-core-messenger@yourdomain.example.service
```

Automate Composer Scripts Add to composer.json:

"scripts": {
    "auto-scripts": {
        "baks:assets:install": "symfony-cmd",
        "baks:cache:clear": "symfony-cmd"
    },
    "post-install-cmd": ["@auto-scripts"],
    "post-update-cmd": ["@auto-scripts"]
}

First Use Case: Messenger Worker Trigger a test message via Laravel’s queue system or Symfony Messenger CLI:
```
php bin/console messenger:consume async -vv
```

Implementation Patterns

Core Workflows

1. Domain-Aware Configuration

Use HOST in .env to scope services (e.g., yourdomain.example-core-messenger@.service).

Extend with additional domain-specific configs in config/core.php:

'domains' => [
    'yourdomain.example' => [
        'timezone' => 'Europe/Moscow',
        'debug' => env('APP_DEBUG', false),
    ],
],

2. Messenger Integration

Laravel Queues → Symfony Messenger: Register a bridge in config/queue.php:

'connections' => [
    'messenger' => [
        'driver' => 'messenger',
        'queue' => env('MESSENGER_QUEUE', 'default'),
    ],
],

Publish a message:

use Symfony\Component\Messenger\MessageBusInterface;
$bus->dispatch(new YourMessage());

3. CLI Automation

Extend baks:* scripts in app/Console/Kernel.php:

protected function commands()
{
    $this->load(__DIR__.'/../vendor/baks-dev/core/src/Console');
}

Call via Artisan:
```
php artisan baks:assets:install
```

4. Systemd Worker Management

Dynamic Service Naming: Use @ syntax in systemd service files to accept domain as a parameter:
```
[Service]
ExecStart=/usr/bin/php /path/to/artisan messenger:consume %i
```

Reload Systemd:

sudo systemctl daemon-reload
sudo systemctl restart yourdomain.example-core-messenger@yourdomain.example.service

5. Asset Pipeline

Integrate with Laravel Mix/Vite by extending baks:assets:install:

// In a custom command
$this->call('vite:build');
$this->call('baks:assets:install');

Integration Tips

Laravel-Symfony Hybrid

Service Provider Bridge:

// app/Providers/CoreServiceProvider.php
public function register()
{
    $this->app->singleton(MessageBusInterface::class, function ($app) {
        return $app->make('bus.messenger');
    });
}

Queue Driver Alias:

// config/queue.php
'aliases' => [
    'messenger' => 'symfony',
],

Testing

Run core tests with:
```
php bin/phpunit --group=core
```

Mock Symfony Messenger in Laravel tests:

$this->app->instance(MessageBusInterface::class, $mockBus);

WebP Conversion (via `files-cdn`)

Configure in config/files-cdn.php:

'conversions' => [
    'webp' => [
        'driver' => 'imagick',
        'quality' => 80,
    ],
],

Use in a controller:

use BaksDev\FilesCdn\Facades\FilesCdn;
$webpPath = FilesCdn::convert('path/to/image.jpg', 'webp');

Gotchas and Tips

Pitfalls

Systemd Dependency

Issue: Systemd workers won’t run in Docker/Kubernetes without adaptation.

Fix: Use supervisord in Docker or Kubernetes CronJob for scheduled tasks. Example Dockerfile:

RUN apt-get update && apt-get install -y supervisor
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

PHP Version Conflict
- Issue: Requires PHP 8.4+, which may conflict with Laravel 10’s PHP 8.2–8.3 support.
- Fix: Pin PHP version in composer.json or use a separate PHP-FPM pool for Symfony components.
CLI Tooling Mismatch
- Issue: baks:* commands use Symfony CLI, not Laravel Artisan.
- Fix: Override commands in app/Console or use Symfony CLI directly:
```
./vendor/bin/symfony-cmd baks:assets:install
```
Domain Configuration Overrides
- Issue: HOST in .env is global; may conflict with multi-tenant setups.
- Fix: Use Laravel’s config() with tenant-aware defaults:
```
config(['core.domain' => tenant()->domain]);
```

Messenger vs. Laravel Queues

Issue: Symfony Messenger doesn’t integrate natively with Laravel Queues.

Fix: Use a queue driver bridge:

// config/queue.php
'connections' => [
    'messenger' => [
        'driver' => 'symfony',
        'queue' => env('MESSENGER_QUEUE', 'default'),
        'bus' => 'bus.messenger',
    ],
],

Asset Pipeline Conflicts
- Issue: baks:assets:install may overwrite Laravel Mix/Vite builds.
- Fix: Disable in composer.json and create a custom script:
```
"scripts": {
    "dev": "mix",
    "prod": "mix --prod"
}
```

Debugging Tips

Systemd Worker Logs

Check logs with:

journalctl -u yourdomain.example-core-messenger@yourdomain.example.service -f

Messenger Debugging

Enable debug mode in config/messenger.php:

'transport' => [
    'dsn' => env('MESSENGER_TRANSPORT_DSN'),
    'options' => [
        'debug' => true,
    ],
],

View consumed messages:

php bin/console messenger:consume debug -vv

Composer Script Debugging
- Run scripts manually to isolate issues:
```
./vendor/bin/symfony-cmd baks:assets:install --verbose
```
PHP Errors in Systemd
- Redirect output in the systemd service file:
```
[Service]
StandardOutput=journal
StandardError=journal
```

Extension Points

Custom Systemd Templates
- Extend templates in vendor/baks-dev/core/Resources/systemd by copying to config/core/systemd/ and overriding paths in config/core.php:
```
'systemd' => [
    'templates_path' => base_path('config/core/systemd'),
],
```

Messenger Middleware

Add custom middleware to config/messenger.php:

'middleware' => [
    \BaksDev\Core\Messenger\Middleware\YourMiddleware::class,
],

Asset Pipeline Hooks
- Extend baks:assets:install by publishing and overriding the command:
```
php artisan vendor:publish --tag=core-assets
```
- Modify app/Console/Commands/BaksAssetsInstall.php.
**

Core Laravel Package