Core Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require artisanpack-ui/core
   

   This registers the CoreServiceProvider automatically.

2. Publish the base config:

   php artisan vendor:publish --tag=artisanpack-config
   

   Creates config/artisanpack.php (empty initially).

3. Scaffold configurations from installed ArtisanPack UI packages:

   php artisan artisanpack:scaffold-config
   

   Merges all package configs into artisanpack.php while preserving existing customizations.

First Use Case

Accessing unified configurations:

// In a controller or service
$cmsSettings = config('artisanpack.cms-framework.settings');
$siteTitle = config('artisanpack.cms-framework.settings.site_title', 'Default Title');

Implementation Patterns

Unified Configuration Workflow

1. Install sibling packages (e.g., artisanpack-ui/cms-framework).
2. Run scaffolding (artisan artisanpack:scaffold-config) to auto-merge configs.
3. Extend config/artisanpack.php with custom values:

   return [
       'cms-framework' => [
           'settings' => [
               'site_title' => 'My Site',
               'theme' => 'dark',
           ],
       ],
       'visual-editor' => [
           'autosave_interval' => 300,
       ],
   ];
   

Service Provider Integration

For new ArtisanPack UI packages:

// app/Providers/MyPackageServiceProvider.php
use ArtisanPackUI\Core\ArtisanPackServiceProvider;

class MyPackageServiceProvider extends ArtisanPackServiceProvider
{
    protected $configFile = 'my-package';
    protected $configKey = 'my-package';
    protected $configPublishTag = 'my-package-config';

    public function registerPackageBindings()
    {
        $this->app->singleton('my-package', function () {
            return new MyPackageManager();
        });
    }
}

Configuration Access Patterns

• Package-wide settings:

  $allConfigs = config('artisanpack');
  

• Package-specific:

  $editorConfig = config('artisanpack.visual-editor');
  

• Fallback defaults:

  $interval = config('artisanpack.visual-editor.autosave_interval', 60);
  

Blade Directives

Register reusable directives in a service provider:

use ArtisanPackUI\Core\Facades\ArtisanPackBlade;

public function boot()
{
    ArtisanPackBlade::directive('myDirective', function ($expression) {
        return "<?php echo 'Processed: ' . {$expression}; ?>";
    });
}

Use in Blade:

@myDirective($variable)

Logging

Leverage the shared logger:

use ArtisanPackUI\Core\Facades\ArtisanPackLog;

ArtisanPackLog::info('User updated CMS settings', [
    'user_id' => 123,
    'package' => 'cms-framework',
]);

// Audit logs (compliance events)
ArtisanPackLog::audit('cms_content_published', [
    'content_id' => 456,
    'author' => 'admin',
]);

Testing

Extend the base test case:

use ArtisanPackUI\Core\Testing\ArtisanPackTestCase;

class MyPackageTest extends ArtisanPackTestCase
{
    public function test_config_merged()
    {
        $this->assertConfigEquals([
            'cms-framework' => [
                'settings' => [
                    'site_title' => 'My Site',
                ],
            ],
        ]);
    }
}

Gotchas and Tips

Pitfalls

1. Configuration Overrides:

   • The --force flag in artisanpack:scaffold-config overwrites existing keys. Use cautiously in production.
   • Tip: Review config/artisanpack.php after scaffolding to spot unintended merges.

2. Package Detection:

   • Only packages tagged with artisanpack-config are auto-detected. Verify with:

     php artisan artisanpack:diagnose
     

3. Facade Availability:

   • Facades like ArtisanPackLog throw ServiceException if the underlying service isn’t bound. Check with:

     if (ArtisanPackLog::isAvailable()) {
         ArtisanPackLog::info('Safe to log');
     }
     

4. Blade Directive Conflicts:

   • Duplicate directive names cause runtime errors. Validate namespaces upfront:

     ArtisanPackBlade::directive('myDirective', ...);
     // Throws if 'myDirective' is already registered.
     

5. Laravel Version Mismatches:

   • Laravel 13 requires PHP 8.3+. Core 1.2+ enforces this via illuminate/support constraints.
   • Debug: Run php artisan artisanpack:check-compatibility to detect version conflicts.

Debugging Tips

• Diagnose Issues:

  php artisan artisanpack:diagnose --json
  

  Outputs structured checks for environment, configs, and bindings.

• Validate Configs: Use the ConfigurationManager facade:

  use ArtisanPackUI\Core\Facades\ArtisanPackConfig;
  
  $result = ArtisanPackConfig::validate('cms-framework', [
      'settings.site_title' => 'required|string',
  ]);
  

• Log Inspection: Audit logs are stored in storage/logs/artisanpack_audit.log (if enabled). Enable via:

  'artisanpack' => [
      'core' => [
          'logging' => [
              'audit' => [
                  'enabled' => true,
              ],
          ],
      ],
  ];
  

Extension Points

1. Custom Configuration Schemas: Register validation rules for package-specific configs:

   ArtisanPackConfig::registerSchema('cms-framework', [
       'settings.site_title' => ['required', 'string', 'max:255'],
       'settings.theme' => ['in:light,dark,modern'],
   ]);
   

2. Dynamic Blade Directives: Extend BladeDirectiveRegistrar to add dynamic directives:

   ArtisanPackBlade::conditional('ifAdmin', function ($expression) {
       return "<?php if(auth()->check() && auth()->user()->is_admin): ?>";
   });
   

3. Package-Specific Logging Channels: Override the default channel in config/artisanpack.php:

   'core' => [
       'logging' => [
           'channel' => 'stack', // or 'single', 'custom_channel'
       ],
   ];
   

4. Custom Diagnostics: Add checks to the DiagnosticRunner:

   $runner = app(DiagnosticRunner::class);
   $runner->addCheck(new MyCustomCheck());
   

Performance Notes

• Configuration Caching: Laravel’s config caching (config:cache) works seamlessly with artisanpack.php. Clear with:

  php artisan config:clear
  

  after manual config changes.

• Update Checks: Cache TTL for artisanpack:check-updates is configurable:

  'core' => [
      'updates' => [
          'cache_ttl' => 7200, // 2 hours
      ],
  ];
  

Migration Tips (v1.1 → v1.2)

1. Service Provider Upgrade: Replace custom providers with ArtisanPackServiceProvider:

   // Before
   class MyProvider extends ServiceProvider { ... }
   
   // After
   class MyProvider extends ArtisanPackServiceProvider { ... }
   

2. Accessibility Helpers: Move a11y() functions to artisanpack-ui/accessibility:

   composer require artisanpack-ui/accessibility
   

3. Testing: Replace TestCase with ArtisanPackTestCase for built-in assertions:

   $this->assertPackageInstalled('artisanpack-ui/cms-framework');