Skeleton Laravel Package

Getting Started

Minimal Steps to Begin

1. Install via GitHub Template

   • Click "Use this template" on the Moox Skeleton GitHub repo to create a new Laravel package repo.
   • Clone your new repo and run:

     composer install
     ./build.php
     

   • This generates a scaffolded Laravel package with Moox conventions.

2. First Use Case: Package Bootstrapping

   • The build.php script initializes:
     • Standard Laravel package structure (src/, config/, tests/).
     • Moox-specific files (e.g., moox.php config, Filament integration hooks).
     • Example service providers, commands, and console helpers.
   • Verify by running:

     php artisan vendor:publish --provider="YourVendor\YourPackage\YourPackageServiceProvider"
     

3. Where to Look First

   • src/: Core package logic (services, models, contracts).
   • config/moox.php: Package configuration (extend this for customization).
   • build.php: Re-run this to regenerate files after major changes.
   • tests/: Example test structure (use Pest/PHPUnit).

Implementation Patterns

Core Workflows

1. Package Development Loop

   • Develop: Write code in src/ (e.g., Services/, Contracts/).
   • Test: Use tests/ with Laravel’s test helpers (e.g., createMock() for contracts).
   • Publish: Run php artisan vendor:publish to expose config/views.
   • Regenerate: Modify build.php or templates in resources/templates/ to update the scaffold.

2. Filament Integration

   • Moox packages often integrate with Filament. Leverage:
     • Resource/Widget Scaffolding: Use moox:filament commands (if available) to generate CRUD interfaces.
     • Service Provider Hooks: Override Filament’s default behavior in YourPackageServiceProvider::boot():

       Filament::serving(function () {
           Filament::registerResource(YourResource::class);
       });
       

   • Shared State: Use moox.php config to share settings between your package and Filament apps.

3. Command-Line Automation

   • Extend build.php to add custom scaffolding. Example:

     // Add to build.php
     if ($this->option('generate:resource')) {
         $this->call('make:filament-resource', ['name' => $this->argument('name')]);
     }
     

   • Register custom Artisan commands in console/Kernel.php:

     protected $commands = [
         Commands\YourCustomCommand::class,
     ];
     

4. Configuration Management

   • Publish and merge config:

     php artisan vendor:publish --tag="moox-config"
     

   • Extend the config in config/moox.php:

     'your_package' => [
         'setting' => env('YOUR_PACKAGE_SETTING', 'default'),
     ],
     

   • Access config in code:

     config('moox.your_package.setting');
     

5. Testing Patterns

   • Use Laravel’s PackageServiceProvider for isolated testing:

     use Tests\CreatesApplication;
     use YourVendor\YourPackage\YourPackageServiceProvider;
     
     class YourPackageTestCase extends TestCase
     {
         use CreatesApplication;
     
         protected function getPackageProviders($app)
         {
             return [YourPackageServiceProvider::class];
         }
     }
     

   • Mock Filament dependencies:

     $filament = Mockery::mock(Filament::class);
     $filament->shouldReceive('registerResource')->once();
     

Gotchas and Tips

Pitfalls

1. Template Overrides

   • Modifying build.php or resources/templates/ after initial generation may break future updates. Tip: Fork the template or document changes.
   • Fix: Use composer.json scripts to customize builds:

     "scripts": {
         "post-autoload-dump": "php build.php --custom-option"
     }
     

2. Filament Version Mismatches

   • Moox packages may assume a specific Filament version. Gotcha: If you update Filament globally, your package might fail.
   • Fix: Pin Filament in composer.json:

     "require": {
         "filament/filament": "^3.0"
     }
     

3. Configuration Caching

   • Changes to config/moox.php require cache clearing:

     php artisan config:clear
     

   • Tip: Use config_cache in config/app.php for development:

     'config_cache' => false,
     

4. Service Provider Loading Order

   • If your package’s service provider runs after Filament’s, hooks (e.g., Filament::serving) may fail.
   • Fix: Ensure your provider is loaded early by adding it to config/app.php under providers.

5. Build Script Dependencies

   • build.php may fail if Composer dependencies are missing. Gotcha: Running ./build.php without composer install first.
   • Fix: Add a check in build.php:

     if (!file_exists(__DIR__.'/vendor/autoload.php')) {
         throw new RuntimeException('Run `composer install` first.');
     }
     

Debugging Tips

1. Log Package Events

   • Use Laravel’s logging in service providers:

     \Log::info('YourPackage initialized', ['config' => config('moox')]);
     

   • Check logs at storage/logs/laravel.log.

2. Artisan Command Debugging

   • Add verbose output to build.php:

     $this->info("Generating files in: {$this->option('path')}");
     

   • Run with --verbose:

     ./build.php --verbose
     

3. Filament Debugging

   • Enable Filament’s debug mode in .env:

     FILAMENT_DEBUG=true
     

   • Check browser console for JavaScript errors.

Extension Points

1. Custom Templates

   • Override default templates by copying files from vendor/moox/skeleton/resources/templates/ to your project’s resources/templates/.

2. Dynamic Configuration

   • Use environment variables in moox.php:

     'api_key' => env('YOUR_PACKAGE_API_KEY'),
     

   • Validate them in a service provider’s boot():

     if (empty(config('moox.api_key'))) {
         throw new RuntimeException('API key not configured.');
     }
     

3. Package Discovery

   • For Laravel 8.30+, use discoverPackages() in composer.json:

     "extra": {
         "laravel": {
             "discover-packages": true
         }
     }
     

4. CI/CD Integration

   • Add a build script to composer.json:

     "scripts": {
         "build": "php build.php && php artisan config:cache"
     }
     

   • Run in CI:

     composer build